Permissions check failed

[EcksDy]

Issue filing pre-requisites

• I've checked the documentation.
• I've looked for similar issues both Open and Closed.
• Ive tried clearing both cache and cookies in my browser or tried opening the app in the Incognito/InPrivate window.

Describe the bug

Hello,
trying to run InvoiceShelf for the first time and ran into a permissions issue.
I'm managing the docker compose via dokploy, it's a convenience wrapper around docker.

Here's the docker-compose.yml:

version: "3.8"
services:
  invoiceshelf-postgres:
    image: postgres:15
    volumes:
      - invoiceshelf-postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_USER=${DB_USERNAME}
      - POSTGRES_DB=${DB_DATABASE}
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -U ${DB_USERNAME}
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - business-invoiceshelf-h3vuml
  invoiceshelf-app:
    image: invoiceshelf/invoiceshelf:nightly
    networks:
      - dokploy-network
      - business-invoiceshelf-h3vuml
    volumes:
      - invoiceshelf_storage:/var/www/html/storage
    environment:
      PHP_TZ: UTC
      TIMEZONE: UTC
      APP_NAME: ${APP_NAME}
      APP_ENV: ${APP_ENV}
      APP_DEBUG: ${APP_DEBUG}
      APP_URL: ${APP_URL}
      DB_CONNECTION: pgsql
      DB_HOST: invoiceshelf-postgres
      DB_PORT: 5432
      DB_DATABASE: ${DB_DATABASE}
      DB_USERNAME: ${DB_USERNAME}
      DB_PASSWORD: ${DB_PASSWORD}
      CACHE_STORE: file
      SESSION_DRIVER: file
      SESSION_LIFETIME: ${SESSION_LIFETIME}
      SESSION_DOMAIN: ${SESSION_DOMAIN}
      SESSION_ENCRYPT: true
      SESSION_PATH: /
      SANCTUM_STATEFUL_DOMAINS: ${SANCTUM_STATEFUL_DOMAINS}
      MAIL_DRIVER: ${MAIL_DRIVER}
      MAIL_HOST: ${MAIL_HOST}
      MAIL_PORT: ${MAIL_PORT}
      MAIL_USERNAME: ${MAIL_USERNAME}
      MAIL_PASSWORD: ${MAIL_PASSWORD}
      MAIL_ENCRYPTION: ${MAIL_ENCRYPTION}
      STARTUP_DELAY: 10
    depends_on:
      invoiceshelf-postgres:
        condition: service_healthy
    labels:
      - # traefik configs
      - traefik.enable=true
networks:
  dokploy-network:
    external: true
  business-invoiceshelf-h3vuml:
    name: business-invoiceshelf-h3vuml
    external: true
volumes:
  invoiceshelf-postgres-data: null
  invoiceshelf_storage: null

I'm using invoiceshelf_storage volume as instructed in the compose upgrade docs.
The network dokploy-network is for access to mailcatcher and business-invoiceshelf-h3vuml as an isolated network for invoiceshelf and its postgres, these are probably unrelated to the problem.

Thanks for your help, I'm eager to try the cool piece of software :)

Steps to Reproduce the issue

1. setup docker-compose
2. run it
3. installation screen shows an issue with permissions

Expected behavior

Running the out of the box setup should not have permission issues

Actual behavior

Permission check fails:

InvoiceShelf version

nightly docker / 2.2.0-alpha2

Database type

PostgreSQL

Database version

15

Web Browser

No response

Server OS

No response

Reverse-proxy logs

Laravel/PHP/Container logs

2025-11-03T10:04:54.364Z -------------------------------------
2025-11-03T10:04:54.364Z InvoiceShelf Version:  2.2.0-alpha2
2025-11-03T10:04:54.364Z -------------------------------------
2025-11-03T10:04:54.369Z **** Setup initial .env values ****
2025-11-03T10:04:54.413Z **** Setting up artisan permissions ****
2025-11-03T10:04:54.416Z --------------------------------------------------------------------
2025-11-03T10:04:54.416Z ____                             ____  _     _        _   _
2025-11-03T10:04:54.416Z / ___|  ___ _ ____   _____ _ __  / ___|(_) __| | ___  | | | |_ __
2025-11-03T10:04:54.416Z \___ \ / _ \  __\ \ / / _ \  __| \___ \| |/ _` |/ _ \ | | | |  _ \
2025-11-03T10:04:54.416Z ___) |  __/ |   \ V /  __/ |     ___) | | (_| |  __/ | |_| | |_) |
2025-11-03T10:04:54.416Z |____/ \___|_|    \_/ \___|_|    |____/|_|\__,_|\___|  \___/| .__/
2025-11-03T10:04:54.416Z |_|
2025-11-03T10:04:54.416Z Brought to you by serversideup.net
2025-11-03T10:04:54.416Z --------------------------------------------------------------------
2025-11-03T10:04:54.489Z 🙌 To support Server Side Up projects visit:
2025-11-03T10:04:54.489Z https://serversideup.net/sponsor
2025-11-03T10:04:54.489Z -------------------------------------
2025-11-03T10:04:54.489Z ℹ️ Container Information
2025-11-03T10:04:54.489Z -------------------------------------
2025-11-03T10:04:54.533Z OS:            Alpine Linux v3.22
2025-11-03T10:04:54.533Z Docker user:   www-data
2025-11-03T10:04:54.533Z Docker uid:    82
2025-11-03T10:04:54.533Z Docker gid:    82
2025-11-03T10:04:54.533Z OPcache:       ✅ Enabled
2025-11-03T10:04:54.533Z PHP Version:   8.3.25
2025-11-03T10:04:54.533Z Image Version: v3.6.0-17759140407
2025-11-03T10:04:54.539Z (init-webserver-config): Processing /etc/nginx/nginx.conf.template → /etc/nginx/nginx.conf...
2025-11-03T10:04:54.547Z (init-webserver-config): Processing /etc/nginx/site-opts.d/http.conf.template → /etc/nginx/site-opts.d/http.conf...
2025-11-03T10:04:54.553Z (init-webserver-config): Processing /etc/nginx/site-opts.d/https.conf.template → /etc/nginx/site-opts.d/https.conf...
2025-11-03T10:04:54.555Z ℹ️ NOTICE (init-webserver-config): Enabling NGINX site with SSL "off"...
2025-11-03T10:04:54.559Z Checking for Laravel automations...
2025-11-03T10:04:54.559Z 🚀 Clearing Laravel cache before attempting migrations...
2025-11-03T10:04:54.972Z INFO  Configuration cache cleared successfully.
2025-11-03T10:04:54.988Z ⚡️ Attempting database connection...
2025-11-03T10:04:55.326Z ✅ Database connection successful.
2025-11-03T10:04:55.326Z 🚀 Running migrations...
2025-11-03T10:04:55.719Z INFO  Nothing to migrate.
2025-11-03T10:04:55.739Z 🔐 Linking the storage...
2025-11-03T10:04:56.069Z INFO  The [public/storage] link has been connected to [storage/app/public].
2025-11-03T10:04:56.083Z 🚀 Caching Laravel config...
2025-11-03T10:04:56.457Z INFO  Configuration cached successfully.
2025-11-03T10:04:56.476Z 🚀 Caching Laravel routes...
2025-11-03T10:04:56.851Z INFO  Routes cached successfully.
2025-11-03T10:04:56.867Z 🚀 Caching Laravel views...
2025-11-03T10:04:57.217Z INFO  Blade templates cached successfully.
2025-11-03T10:04:57.231Z 🚀 Caching Laravel events...
2025-11-03T10:04:57.549Z INFO  Events cached successfully.
2025-11-03T10:04:57.748Z [03-Nov-2025 10:04:57] NOTICE: [pool www] 'user' directive is ignored when FPM is not running as root
2025-11-03T10:04:57.748Z [03-Nov-2025 10:04:57] NOTICE: [pool www] 'group' directive is ignored when FPM is not running as root
2025-11-03T10:04:57.748Z [03-Nov-2025 10:04:57] NOTICE: fpm is running, pid 156
2025-11-03T10:04:57.750Z [03-Nov-2025 10:04:57] NOTICE: ready to handle connections
2025-11-03T10:04:58.735Z ✅ NGINX + PHP-FPM is running correctly.
2025-11-03T10:05:14.537Z 10.0.1.36 - - [03/Nov/2025:10:05:14 +0000] "GET /installation HTTP/1.1" 200 653 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:145.0) Gecko/20100101 Firefox/145.0" "192.168.112.1"
2025-11-03T10:05:14.862Z 10.0.1.36 - - [03/Nov/2025:10:05:14 +0000] "GET /api/v1/installation/wizard-step HTTP/1.1" 200 68 "https://invoice.800842.xyz/installation" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:145.0) Gecko/20100101 Firefox/145.0" "192.168.112.1"
2025-11-03T10:05:14.872Z 10.0.1.36 - - [03/Nov/2025:10:05:14 +0000] "GET /api/v1/installation/languages HTTP/1.1" 200 426 "https://invoice.800842.xyz/installation" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:145.0) Gecko/20100101 Firefox/145.0" "192.168.112.1"
2025-11-03T10:05:15.635Z 10.0.1.36 - - [03/Nov/2025:10:05:15 +0000] "GET /api/v1/installation/requirements HTTP/1.1" 200 184 "https://invoice.800842.xyz/installation" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:145.0) Gecko/20100101 Firefox/145.0" "192.168.112.1"
2025-11-03T10:05:16.982Z 10.0.1.36 - - [03/Nov/2025:10:05:16 +0000] "GET /api/v1/installation/permissions HTTP/1.1" 200 144 "https://invoice.800842.xyz/installation" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:145.0) Gecko/20100101 Firefox/145.0" "192.168.112.1"

Other logs

[rihards-simanovics]

It may be caused by the entrypoint script not setting the permissions by default. @gdarko, are we able to modify said entrypoint script to inject extra instructions in the base Docker image?

[EcksDy]

I was able to continue and complete a basic setup.
Will I be able to continue using the current volume or should I use a new one?

[rihards-simanovics]

You may need to run docker exec as root and correct permissions using the command in the docs.

[hardysim]

Could you point us to the correct command / link to the docs? I'm running into the same problem by just cloning the repo and doing docker compose up. Is there more to do?

Using the provided run with docker command does not start the webserver at all so this doesn't work either.

[rihards-simanovics]

Could you point us to the correct command / link to the docs?

https://docs.invoiceshelf.com/install/manual.html#step-3-fix-file-permissions

In docker, you will need to open interactive shell into container as a root use.