Self-Host Invoice Ninja on Ubuntu 24.04 with Docker Compose

Aybars Altınyay
Aybars Altınyay
Platform Engineer & Technical Writer
IntermediateUpdated 28 min read~45+ minutes total
Invoice NinjaDocker ComposeUbuntu 24.04MySQLRedisCaddySelf-Hosted InvoicingBackup
Last reviewed:
Tutorial
Self-Host Invoice Ninja on Ubuntu 24.04 with Docker Compose
rafftechnologies.com/learn

Prerequisites

  • An Ubuntu 24.04 VM with SSH sudo access, a domain pointed to the VM, ports 80/443 available, a tested recovery path before firewall changes, and a secure off-server backup destination

Keep your invoices and client data on your own Invoice Ninja server.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month

  1. 1Pick a Linux imageUbuntu, Debian and more, with your SSH key added.
  2. 2Choose a sizeFrom $4.99 a month. Resize when your app grows.
  3. 3Connect over SSHYour server is up in about 55 seconds.

Ubuntu, Debian and other Linux distributions with full root and SSH access, up and running in about 55 seconds.

Invoice Ninja is a self-hosted invoicing and business workflow platform for invoices, quotes, expenses, clients, recurring billing, tasks, and payments. On Ubuntu 24.04, the current official Docker direction is the Debian-based Invoice Ninja image with MySQL, Redis, persistent application volumes, and a reverse proxy for HTTPS.

The original tutorial used a Raff Linux VM as the Ubuntu 24.04 host. The saved tested environment remains Raff VM with 2 vCPU, 4 GB DDR5 RAM, 40 GB NVMe storage, Ubuntu 24.04 LTS. This revision re-verifies the deployment guidance against current Invoice Ninja documentation, Docker files, and image tags on September 5, 2026 without claiming a new end-to-end machine test.

This guide pins Invoice Ninja 5.13.37, the current Debian-image release at verification time. It also corrects an important operational detail that older tutorials often miss: the current Debian container includes two Laravel queue workers and the Laravel scheduler under Supervisord, so you do not need a separate host cron job or queue container when you use the current official Debian image as shown here.

The application container remains private. Only Caddy publishes ports 80 and 443. MySQL, Redis, Nginx, PHP-FPM, queue workers, and the scheduler stay inside the Docker network.

Prerequisites:

  • Ubuntu 24.04 with SSH and sudo access
  • A domain such as billing.example.com pointing to the VM
  • Public TCP 80 and 443 available for HTTPS
  • A tested recovery path before firewall changes
  • A secure off-server destination for Invoice Ninja backups

Step 1 — Verify Ubuntu, DNS, resources, and existing listeners

Confirm the operating system and architecture:

Bash
cat /etc/os-release uname -m

Check memory, CPU, and free disk space:

Bash
nproc free -h df -h /

Set your Invoice Ninja domain and verify DNS:

Bash
export INVOICE_NINJA_DOMAIN=billing.example.com dig +short A "$INVOICE_NINJA_DOMAIN" dig +short AAAA "$INVOICE_NINJA_DOMAIN"

Only publish an AAAA record if IPv6 actually reaches this server and is protected consistently.

Inspect current listeners:

Bash
sudo ss -tulpn

Ports 80 and 443 should be available for Caddy. No Invoice Ninja, MySQL, or Redis port will be published directly on the host.

Verify: Ubuntu should report 24.04, DNS should resolve to this VM, resource headroom should be understood, and no unexpected production service should already own TCP 80 or 443.

Step 2 — Install Docker Engine and Docker Compose v2

Install Docker from Docker's official Ubuntu repository:

Bash
sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc

Add the repository:

Bash
sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF Types: deb URIs: https://download.docker.com/linux/ubuntu Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") Components: stable Architectures: $(dpkg --print-architecture) Signed-By: /etc/apt/keyrings/docker.asc EOF

Install Docker Engine and Compose:

Bash
sudo apt update sudo apt install -y \ docker-ce docker-ce-cli containerd.io \ docker-buildx-plugin docker-compose-plugin sudo systemctl enable --now docker

Verify:

Bash
sudo docker version docker compose version sudo docker run --rm hello-world

For a standalone walkthrough, see Install Docker on Ubuntu 24.04.

Verify: Docker should be active, Compose v2 should respond, and the hello-world container should run successfully.

Step 3 — Prepare the firewall without risking SSH lockout

Open a second SSH session before changing firewall state.

If UFW is already active, verify your real SSH rule and allow HTTP/HTTPS:

Bash
sudo ufw status numbered sudo ufw allow 80/tcp comment 'Invoice Ninja HTTP/ACME' sudo ufw allow 443/tcp comment 'Invoice Ninja HTTPS'

If UFW is inactive, do not enable it blindly from a single remote shell. Follow the lockout-safe procedure in Set Up UFW Firewall on Ubuntu 24.04.

Do not open MySQL 3306, Redis 6379, PHP-FPM 9000, or an internal Nginx port publicly.

Verify: SSH should remain reachable from the second session, only the required public web ports should be allowed, and there should be no public firewall rule for MySQL, Redis, or Invoice Ninja internals.

Step 4 — Create the deployment directories and production secrets

Create the stack directories:

Bash
sudo mkdir -p /opt/invoice-ninja/{nginx,backups} sudo chown -R "$USER":"$USER" /opt/invoice-ninja cd /opt/invoice-ninja chmod 700 backups

Generate an Invoice Ninja/Laravel application key from 32 random bytes:

Bash
APP_KEY="base64:$(openssl rand -base64 32 | tr -d '\n')"

Generate database credentials and a one-time bootstrap administrator password:

Bash
DB_PASSWORD="$(openssl rand -hex 32)" DB_ROOT_PASSWORD="$(openssl rand -hex 32)" INITIAL_ADMIN_PASSWORD="$(openssl rand -base64 24 | tr -d '\n')" printf '%s\n' "$INITIAL_ADMIN_PASSWORD" > .initial_admin_password chmod 600 .initial_admin_password

Prompt for the administrator email:

Bash
read -rp 'Initial Invoice Ninja admin email: ' IN_USER_EMAIL read -rp 'Invoice Ninja domain (for example billing.example.com): ' INVOICE_NINJA_DOMAIN read -rp 'ACME certificate email: ' ACME_EMAIL

Verify: .initial_admin_password should exist with mode 600, and the generated application/database secrets should not be written into shell history manually.

Step 5 — Create a current Invoice Ninja 5.13.37 environment file

Create .env:

Bash
cat > .env <<EOF APP_URL=https://${INVOICE_NINJA_DOMAIN} APP_KEY=${APP_KEY} APP_ENV=production APP_DEBUG=false REQUIRE_HTTPS=true NINJA_ENVIRONMENT=selfhost IS_DOCKER=true PHANTOMJS_PDF_GENERATION=false PDF_GENERATOR=snappdf TRUSTED_PROXIES='*' CACHE_DRIVER=redis QUEUE_CONNECTION=redis SESSION_DRIVER=redis REDIS_HOST=redis REDIS_PASSWORD=null REDIS_PORT=6379 FILESYSTEM_DISK=debian_docker DB_CONNECTION=mysql DB_HOST=mysql DB_PORT=3306 DB_DATABASE=ninja DB_USERNAME=ninja DB_PASSWORD=${DB_PASSWORD} DB_ROOT_PASSWORD=${DB_ROOT_PASSWORD} IN_USER_EMAIL=${IN_USER_EMAIL} IN_PASSWORD=${INITIAL_ADMIN_PASSWORD} MAIL_MAILER=log MAIL_HOST=smtp.example.com MAIL_PORT=587 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=null MAIL_FROM_ADDRESS=${IN_USER_EMAIL} MAIL_FROM_NAME='Invoice Ninja' MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD} MYSQL_USER=ninja MYSQL_PASSWORD=${DB_PASSWORD} MYSQL_DATABASE=ninja SCOUT_DRIVER=null ACME_EMAIL=${ACME_EMAIL} INVOICE_NINJA_DOMAIN=${INVOICE_NINJA_DOMAIN} EOF chmod 600 .env

The current official Debian Docker example uses Redis for cache, queues, and sessions and sets IS_DOCKER=true. It also uses FILESYSTEM_DISK=debian_docker and supports Snappdf with Chrome/Chromium built into the Debian image.

TRUSTED_PROXIES='*' follows the current Docker example. In this architecture the application container is never published directly; only the private Docker network can reach it. If you later place the application on a broader network or expose it outside this Compose project, restrict trusted proxies to the actual proxy CIDR.

Keep MAIL_MAILER=log until the deployment is verified. Configure real SMTP only after login, queues, scheduler, PDF generation, and backups work.

Verify: .env should be mode 600, APP_ENV=production, APP_DEBUG=false, REQUIRE_HTTPS=true, QUEUE_CONNECTION=redis, and the bootstrap credentials should still be present for first startup only.

Step 6 — Create the pinned Docker Compose stack

Create compose.yaml:

Bash
cat > compose.yaml <<'EOF' services: app: image: invoiceninja/invoiceninja-debian:5.13.37 container_name: invoice-ninja-app restart: unless-stopped env_file: - ./.env volumes: - invoice_ninja_app_public:/var/www/html/public - invoice_ninja_app_storage:/var/www/html/storage depends_on: mysql: condition: service_healthy redis: condition: service_healthy networks: - invoice_ninja_net nginx: image: nginx:alpine container_name: invoice-ninja-nginx restart: unless-stopped volumes: - ./nginx:/etc/nginx/conf.d:ro - invoice_ninja_app_public:/var/www/html/public:ro - invoice_ninja_app_storage:/var/www/html/storage:ro depends_on: app: condition: service_healthy networks: - invoice_ninja_net mysql: image: mysql:8.4 container_name: invoice-ninja-mysql restart: unless-stopped environment: MYSQL_DATABASE: ${MYSQL_DATABASE} MYSQL_USER: ${MYSQL_USER} MYSQL_PASSWORD: ${MYSQL_PASSWORD} MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} volumes: - invoice_ninja_mysql_data:/var/lib/mysql healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u${MYSQL_USER}", "-p${MYSQL_PASSWORD}"] interval: 10s timeout: 5s retries: 10 networks: - invoice_ninja_net redis: image: redis:7.4-alpine container_name: invoice-ninja-redis restart: unless-stopped volumes: - invoice_ninja_redis_data:/data healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 10 networks: - invoice_ninja_net caddy: image: caddy:2 container_name: invoice-ninja-caddy restart: unless-stopped depends_on: - nginx ports: - "80:80" - "443:443" environment: INVOICE_NINJA_DOMAIN: ${INVOICE_NINJA_DOMAIN} ACME_EMAIL: ${ACME_EMAIL} volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - invoice_ninja_caddy_data:/data - invoice_ninja_caddy_config:/config networks: - invoice_ninja_net networks: invoice_ninja_net: driver: bridge volumes: invoice_ninja_app_public: name: invoice_ninja_app_public invoice_ninja_app_storage: name: invoice_ninja_app_storage invoice_ninja_mysql_data: name: invoice_ninja_mysql_data invoice_ninja_redis_data: name: invoice_ninja_redis_data invoice_ninja_caddy_data: name: invoice_ninja_caddy_data invoice_ninja_caddy_config: name: invoice_ninja_caddy_config EOF

Invoice Ninja's older invoiceninja/invoiceninja image now carries a deprecation notice directing users to the Debian-based image. This guide therefore pins the current Debian release rather than using the mutable latest tag.

Verify: The app image should be exactly invoiceninja/invoiceninja-debian:5.13.37, MySQL/Redis should have no ports: block, and only Caddy should publish ports 80/443.

Step 7 — Create the internal Nginx and public Caddy reverse-proxy configuration

Create the Nginx snippets used by the official Debian layout:

Bash
cat > nginx/invoiceninja.conf <<'EOF' client_max_body_size 20M; client_body_buffer_size 20M; server_tokens off; fastcgi_buffers 32 16K; gzip on; gzip_comp_level 2; gzip_min_length 1M; gzip_proxied any; gzip_types *; EOF

Create the Laravel Nginx virtual host:

Bash
cat > nginx/laravel.conf <<'EOF' server { listen 80 default_server; server_name _; root /var/www/html/public; index index.php; charset utf-8; add_header X-Frame-Options "SAMEORIGIN"; add_header X-Content-Type-Options "nosniff"; location / { try_files $uri $uri/ /index.php?$query_string; } location = /favicon.ico { access_log off; log_not_found off; } location = /robots.txt { access_log off; log_not_found off; } error_page 404 /index.php; location ~ \.php$ { fastcgi_pass app:9000; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include fastcgi_params; } location ~ /\.(?!well-known).* { deny all; } } EOF

Create Caddyfile:

Bash
cat > Caddyfile <<'EOF' { email {$ACME_EMAIL} } {$INVOICE_NINJA_DOMAIN} { encode zstd gzip header { Strict-Transport-Security "max-age=31536000" X-Content-Type-Options "nosniff" X-Frame-Options "SAMEORIGIN" Referrer-Policy "same-origin" -Server } reverse_proxy nginx:80 } EOF

Validate the Compose model:

Bash
sudo docker compose config >/dev/null && echo 'Compose config is valid'

Verify: The Compose file should validate, Caddy should proxy only to the private Nginx service, and neither Nginx nor PHP-FPM should be directly exposed on the host.

Step 8 — Start Invoice Ninja and verify the built-in health check

Pull all images first:

Bash
cd /opt/invoice-ninja sudo docker compose pull

Start the stack:

Bash
sudo docker compose up -d

Inspect service state:

Bash
sudo docker compose ps

The current Debian Invoice Ninja image includes an application health check that calls the internal /health route through PHP-FPM.

Inspect the app health status:

Bash
sudo docker inspect \ --format '{{.State.Health.Status}}' \ invoice-ninja-app

Check MySQL and Redis:

Bash
DB_PASSWORD="$(sed -n 's/^DB_PASSWORD=//p' .env)" sudo docker compose exec -T mysql \ mysqladmin ping -h localhost -uninja -p"$DB_PASSWORD" sudo docker compose exec -T redis redis-cli ping

Test HTTPS:

Bash
INVOICE_NINJA_DOMAIN="$(sed -n 's/^INVOICE_NINJA_DOMAIN=//p' .env)" curl -I "https://$INVOICE_NINJA_DOMAIN"

Verify: The app container should become healthy, MySQL should report alive, Redis should return PONG, Caddy should obtain a trusted certificate, and the public domain should respond over HTTPS.

Step 9 — Verify the queue workers and scheduler managed by Supervisord

The current Debian image starts three application-side process groups automatically:

  • PHP-FPM;
  • two queue:work processes;
  • one schedule:work process.

Check Supervisord from inside the app container:

Bash
sudo docker compose exec app supervisorctl status

Expected process names include:

Text
php-fpm queue-worker_00 queue-worker_01 scheduler

You can also inspect the process list:

Bash
sudo docker compose exec app ps aux | grep -E \ 'php-fpm|queue:work|schedule:work' | grep -v grep

This is why this Docker deployment does not need the host cron line commonly used by manual Invoice Ninja installations:

Text
* * * * * php artisan schedule:run

Do not run a duplicate host scheduler unless you intentionally redesign the process model.

Verify: PHP-FPM, both queue workers, and the scheduler should all report RUNNING. Recurring invoices and scheduled notifications depend on this scheduler/queue path, so do not consider the deployment production-ready if these processes are missing.

Step 10 — Log in, rotate the bootstrap password, and remove bootstrap credentials

Display the bootstrap email and temporary password only when needed:

Bash
grep '^IN_USER_EMAIL=' /opt/invoice-ninja/.env sudo cat /opt/invoice-ninja/.initial_admin_password

Open:

Text
https://billing.example.com

Use the existing tutorial screenshots as visual references:

Invoice Ninja login page

Invoice Ninja dashboard

After the first successful login:

  1. Change the administrator password in Invoice Ninja.
  2. Sign out and sign back in with the new password.
  3. Create one disposable test client.
  4. Confirm the client persists after refresh.
  5. Delete the disposable test client after verification.

Remove the bootstrap variables from .env:

Bash
cd /opt/invoice-ninja sed -i '/^IN_USER_EMAIL=/d;/^IN_PASSWORD=/d' .env rm -f .initial_admin_password sudo docker compose up -d app nginx

The official Debian image warns that if those variables are not explicitly set on first initialization, defaults can be used. They are useful for first-run bootstrap only and should not remain in the long-lived production configuration.

Verify: The rotated administrator credentials should work, bootstrap variables should be absent from .env, the temporary password file should be gone, and Invoice Ninja should remain healthy after the app container is recreated.

Step 11 — Verify PDF generation, scheduler health, and outbound-email readiness

Invoice Ninja's current Debian image includes Chrome/Chromium for Snappdf PDF generation.

Create a disposable draft invoice or quote in the UI and preview/download its PDF. Do not send it to a real client during this test.

Check application logs if PDF generation fails:

Bash
sudo docker compose logs --tail=200 app

Verify scheduler and queue processes again:

Bash
sudo docker compose exec app supervisorctl status

For the initial deployment, outbound mail intentionally remains logged rather than sent:

Bash
grep '^MAIL_' /opt/invoice-ninja/.env

When you are ready to send real invoices and reminders, replace the mail settings with your SMTP provider's values and recreate the app container:

Bash
sudo docker compose up -d app

Then send a test message to an address you control and confirm delivery before enabling real recurring workflows.

Verify: A test PDF should render successfully, queue/scheduler processes should remain running, and SMTP should either remain intentionally disabled via MAIL_MAILER=log or be tested successfully with a real provider.

Step 12 — Create a matched database, application-data, and configuration backup

A recoverable Invoice Ninja deployment requires more than MySQL. Preserve:

  • the MySQL database;
  • the persistent /var/www/html/storage volume;
  • the persistent /var/www/html/public volume;
  • .env, Compose, Nginx, and Caddy configuration.

To keep the application files and database closely aligned, stop the web/application path briefly while leaving MySQL available:

Bash
cd /opt/invoice-ninja STAMP="$(date -u +%Y%m%d-%H%M%S)" DB_NAME="$(sed -n 's/^DB_DATABASE=//p' .env)" DB_USER="$(sed -n 's/^DB_USERNAME=//p' .env)" DB_PASSWORD="$(sed -n 's/^DB_PASSWORD=//p' .env)" sudo docker compose stop caddy nginx app

Create a consistent InnoDB dump:

Bash
sudo docker compose exec -T mysql \ mysqldump \ --single-transaction \ --quick \ --routines \ --triggers \ -u"$DB_USER" -p"$DB_PASSWORD" "$DB_NAME" \ | gzip > "backups/invoice-ninja-db-${STAMP}.sql.gz"

Archive the persistent app volumes:

Bash
sudo docker run --rm \ -v invoice_ninja_app_public:/app_public:ro \ -v invoice_ninja_app_storage:/app_storage:ro \ -v /opt/invoice-ninja/backups:/backup \ alpine:3.20 \ tar -czf "/backup/invoice-ninja-files-${STAMP}.tar.gz" \ -C / app_public app_storage

Create a sensitive configuration bundle:

Bash
sudo tar -czf "backups/invoice-ninja-config-${STAMP}.tar.gz" \ compose.yaml Caddyfile nginx .env sudo chmod 600 backups/invoice-ninja-*.sql.gz backups/invoice-ninja-*.tar.gz

Start the application path again:

Bash
sudo docker compose start app nginx caddy

Validate the archives:

Bash
gzip -t "backups/invoice-ninja-db-${STAMP}.sql.gz" sudo tar -tzf "backups/invoice-ninja-files-${STAMP}.tar.gz" | head sudo tar -tzf "backups/invoice-ninja-config-${STAMP}.tar.gz" | head

Copy the backup set to protected off-server storage. Raff Data Protection can provide a VM-level recovery layer, while Object Storage can be used by S3-compatible backup tooling.

Verify: The database dump, app-data archive, and configuration bundle should all be readable, Invoice Ninja should return to healthy, and at least one complete backup set should exist outside the VM.

Step 13 — Test a restore in an isolated environment

Do not prove backups by overwriting production. Restore into a disposable VM or isolated Compose project.

A recovery test should use the same Invoice Ninja image tag first:

Text
invoiceninja/invoiceninja-debian:5.13.37

Restore sequence:

  1. Start a clean MySQL-compatible service.
  2. Restore .env and the Compose/proxy configuration.
  3. Restore the app_public and app_storage volume contents.
  4. Import the MySQL dump into the ninja database.
  5. Start Redis and the Invoice Ninja app.
  6. Allow the app entrypoint to perform its normal startup checks/migrations for that same version.
  7. Start Nginx/Caddy on isolated test DNS.
  8. Sign in and verify clients, invoices, attachments, PDFs, queue workers, and scheduler state.

Example database import pattern:

Bash
gunzip -c invoice-ninja-db-YYYYMMDD-HHMMSS.sql.gz \ | mysql -uninja -p ninja

Use the equivalent command inside the recovery MySQL container with the matching credentials.

Disable or redirect SMTP, payment webhooks, and any external automation before starting a restored test copy so it cannot send real invoices or trigger real integrations.

Verify: The restored instance should log in successfully, representative invoices/clients/files should exist, PDF generation should work, queue/scheduler processes should be running, and the test environment should not contact production customers or payment endpoints.

Step 14 — Update Invoice Ninja safely and run the final exposure audit

The current official Docker update guidance is to pull the new image and recreate the containers. For a pinned production deployment, first review the new release, change the app tag deliberately, and create a full backup from Step 12.

Check the currently configured tag:

Bash
grep 'invoiceninja/invoiceninja-debian' /opt/invoice-ninja/compose.yaml

When moving from 5.13.37 to a reviewed newer release, edit the exact image tag, then run:

Bash
cd /opt/invoice-ninja sudo docker compose pull app sudo docker compose up -d app nginx caddy

The current Debian image entrypoint runs production migrations and cache/design update steps during startup. That is convenient, but it also means a database migration may happen when a new image starts. Do not assume that changing the image tag back is a complete rollback after a migration; keep the pre-update database/files backup until the new version is fully verified.

After the update, check:

Bash
sudo docker compose ps sudo docker inspect --format '{{.State.Health.Status}}' invoice-ninja-app sudo docker compose exec app supervisorctl status sudo docker compose logs --tail=200 app

Run the final host exposure audit:

Bash
sudo docker ps --format 'table {{.Names}}\t{{.Ports}}' sudo ss -tulpn sudo ufw status numbered

Confirm all of the following:

  • Invoice Ninja uses the reviewed Debian image version;
  • only Caddy publishes public TCP 80/443;
  • Nginx, PHP-FPM, MySQL, and Redis remain private;
  • APP_ENV=production, APP_DEBUG=false, and REQUIRE_HTTPS=true;
  • bootstrap admin variables are removed;
  • the app health check reports healthy;
  • two queue workers are running;
  • the Laravel scheduler is running;
  • PDFs render with Snappdf;
  • SMTP is either intentionally disabled or tested;
  • a complete database/files/configuration backup exists off-server;
  • restore testing has been completed;
  • updates are backed up before the new image starts and runs migrations.

Verify: There should be no unintended public database/cache/application listener, no leftover bootstrap password, no stopped scheduler/queue process, no untested PDF path, and no update plan that relies only on changing Docker tags for rollback.

Troubleshooting

The app container never becomes healthy

Inspect the app and database logs:

Bash
cd /opt/invoice-ninja sudo docker compose logs --tail=200 app sudo docker compose logs --tail=200 mysql sudo docker compose ps

The Debian image health check expects the internal /health route to return the Invoice Ninja API health response through PHP-FPM.

Recurring invoices or reminders do not run

Check the scheduler and queue workers first:

Bash
sudo docker compose exec app supervisorctl status

The current Debian image should show two queue workers plus a scheduler. Do not add another host cron before confirming the built-in scheduler has actually failed.

Invoice Ninja shows a 502 error

Check the proxy/application chain:

Bash
sudo docker compose ps sudo docker compose logs --tail=200 caddy sudo docker compose logs --tail=200 nginx sudo docker compose logs --tail=200 app

The expected path is Caddy → private Nginx → app PHP-FPM on port 9000.

MySQL is unhealthy after changing .env

Changing the password in .env does not automatically change the password stored inside an existing MySQL data volume. Rotate the MySQL account credential and .env together as one controlled operation. Do not delete the MySQL volume to fix a password mismatch unless you intentionally want to erase the database.

PDF generation fails

The current Debian image includes Chrome on amd64 and Chromium on arm64 and sets the Snappdf browser path automatically at container startup. Check app logs first:

Bash
sudo docker compose logs --tail=200 app

Also verify PDF_GENERATOR=snappdf and that the application URL is reachable from the container.

The app fails after an image update

Stop the new application container and use the pre-update recovery set. Because the production entrypoint can run database migrations automatically, do not assume that simply restoring the old image tag is enough. Restore the pre-update database and matching app-data files when required.

Conclusion

You now have a current Invoice Ninja self-hosting pattern for Ubuntu 24.04 using the official Debian-based 5.13.37 image, MySQL, Redis, Nginx, Caddy HTTPS, built-in queue workers and scheduler, persistent application data, verified health checks, matched backups, restore testing, and a controlled update process.

The major 2026 corrections are operational rather than cosmetic: avoid the deprecated older Docker image, avoid a mutable latest tag for production, understand that the Debian image already supervises queues and scheduling, and treat every image update as a potential database migration event that requires a proven pre-update recovery point.

For additional operating-system hardening, see Harden Ubuntu 24.04. Docker installation and firewall setup are linked alongside the relevant steps above.

Deploy a Raff Ubuntu Linux VM for Invoice Ninja with a private MySQL and Redis stack, HTTPS, persistent files, and a tested off-server recovery workflow.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month · 14-day money-back guarantee

Deploy Your Server
Was this article helpful?
Aybars Altınyay
Aybars Altınyay
Platform Engineer & Technical Writer

Aybars is a Platform Engineer & Technical Writer at Raff Technologies. He works on Linux VM templates, self-hosted application workflows, and security-focused deployment validation, turning tested infrastructure procedures into clear, practical tutorials for developers and teams.

Keep your invoices and client data on your own Invoice Ninja server.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month

Ubuntu, Debian and other Linux distributions with full root and SSH access, up and running in about 55 seconds.

14-day money-back guarantee

Frequently asked questions

What Invoice Ninja Docker image should I use in September 2026?
Use the official Debian-based image. This guide pins `invoiceninja/invoiceninja-debian:5.13.37`, the current Debian release at verification time. The older `invoiceninja/invoiceninja` image carries a deprecation notice pointing users to the Debian image.
Does Invoice Ninja Docker need a separate cron container?
Not with the current official Debian image used here. Its Supervisord configuration starts two Laravel queue workers and one `php artisan schedule:work` scheduler automatically alongside PHP-FPM.
Why does this guide avoid the latest tag?
A mutable `latest` tag can change without a Compose-file edit and may run database migrations at startup. Pinning an exact release makes updates auditable and lets you create a matching pre-update recovery point.
Why does Invoice Ninja use Redis in this stack?
The official Docker environment uses Redis for cache, queues, and sessions. The current Debian image supervises the queue workers internally when `QUEUE_CONNECTION=redis` is configured.
How do I know the Invoice Ninja application is healthy?
The Debian image defines a Docker health check against the internal `/health` API route through PHP-FPM. `docker inspect` should report the app container as `healthy` after startup completes.
What should I back up for Invoice Ninja?
Back up the MySQL database, the persistent application `public` and `storage` volumes, and the sensitive configuration including `.env`, Compose, Nginx, and Caddy files. Keep at least one complete set off-server and test a restore.
Can I roll back an Invoice Ninja update by changing only the Docker image tag?
Do not rely on that. The Debian production entrypoint can run database migrations during startup, so a safe rollback may require restoring the pre-update database and matching application-data volumes as well as the old image tag.
Does the Invoice Ninja Debian image include PDF support?
Yes. The current Debian image includes Chrome on amd64 or Chromium on arm64 and configures Snappdf support. Verify PDF generation with a disposable draft invoice before storing or sending production billing data.