Workload · Running your own invoicing

Invoice Ninja self hosted on a server of your own

To run Invoice Ninja v5 yourself you need a Linux server with PHP 8.2, MySQL 5.7+ or MariaDB 10.3+ and HTTPS in front, or the project's official Debian Docker image, plus a scheduler that fires every minute and a queue worker so invoices, reminders and PDFs go out on time. This page walks through both install routes, the mail settings, and the backups that keep years of client history safe.

The short version
  1. Two install routes covered here: the official Debian Docker image or a manual tarball install
  2. The scheduler cron and a queue worker are what make reminders and emails actually send
  3. Back up three things: the database, the storage files and the APP_KEY
  4. Your own machine, root access and an unmetered port, month to month

What Invoice Ninja asks of a server

Invoice Ninja is a Laravel application, so it needs a PHP and MySQL stack, a web server with HTTPS, and two background jobs. The project publishes software prerequisites, not a CPU or memory minimum, so size for what else the machine will carry rather than for a number you will not find in the docs.

PartWhat the docs ask forWhat it means for you
PHP8.2 with bcmath, ctype, imagick, soap, gd, mbstring, openssl, tokenizer, xml, curl, zip, gmp, iconv, mysqli, intl, and FPM for nginxInstall them before running setup
DatabaseMySQL 5.7+ or MariaDB 10.3+One database and one user with full rights on it
Web servernginx or Apache with HTTPS enabledServe a domain or subdomain root; subfolders are not supported
SchedulerA cron entry that runs every minuteWithout it, recurring invoices, reminders and exchange-rate updates stall
QueueA worker managed by Supervisor, or a cron worker every 5 minutesThe docs say switching from the default sync mode makes the app faster
Updates1024M PHP memory_limit for the built-in self-updaterSet it before you press the update button on a tarball install

On the Docker image, PDFs are drawn by a bundled headless Chrome, so leave memory for it when many people print or email invoices.

Docker or manual: pick the route you will maintain

Choose Docker for the whole stack in one rebuildable file; choose the manual install if you already run nginx and PHP and want every package in your own hands. The official Debian Compose stack runs nginx, MySQL 8 and Redis beside the app, whose image bundles Chrome for PDFs and the Saxon engine for e-invoice validation. The manual route is a tarball from the GitHub releases page, unpacked into your web root.

The image wiki lists Linux x86_64 as the only supported platform and says ARM is not supported. Use an Intel or AMD machine for Docker.

Up and running with the official Docker image

Install Docker with its Compose plugin first, then fetch the Debian branch of the project's dockerfiles repository:

git clone https://github.com/invoiceninja/dockerfiles.git -b debian
cd dockerfiles/debian
  1. Generate your own encryption key (command below) and copy the whole base64:... string. The repository's .env carries a sample key; never reuse it.
  2. Open .env and set APP_URL to your real https address, APP_KEY to the key you just made, APP_DEBUG=false, and strong values for DB_PASSWORD and DB_ROOT_PASSWORD. The database is created from these on the very first start, so changing them later will not change the existing database user.
  3. Set IN_USER_EMAIL and IN_PASSWORD to your own admin login before the first start. Left empty, the container creates a default admin whose login is printed in the public README, so anyone who reaches the page first can sign in. Remove both lines once the account exists.
  4. Keep the plain-HTTP port private. The stack's nginx container publishes port 80 on every address; in docker-compose.yml change it to 127.0.0.1:8080:80 and [::1]:8080:80, put an HTTPS reverse proxy in front, and set REQUIRE_HTTPS=true. Docker's docs warn that published ports skip ufw rules.
  5. Start the stack and open your address. When the setup asks for a database host, it is mysql.
docker run --rm -it invoiceninja/invoiceninja-debian php artisan key:generate --show
docker compose up -d

The app reads .env through env_file, so a plain restart does not pick up edits. After changing it, run docker compose up -d --force-recreate.

The manual route, step by step

  1. Install PHP 8.2 with the extensions above, MySQL or MariaDB, and nginx or Apache with a certificate.
  2. Download invoiceninja.tar from the GitHub releases and unpack it into your vhost, for example /var/www/invoiceninja, with the web server's root pointed at its public folder.
  3. Give the web user ownership: sudo chown -R www-data:www-data /var/www/invoiceninja and set folders to 755 with sudo find /var/www/invoiceninja -type d -exec chmod 755 {} \;. Nothing needs 777.
  4. Create the database and a user with full rights on it.
  5. Add the scheduler to the web user's crontab: * * * * * cd /var/www/invoiceninja && php artisan schedule:run >> /dev/null 2>&1
  6. Open https://your-domain/setup and enter the database details. Do this straight after installing: until the wizard is finished, whoever reaches that page first sets the install up.
  7. Run the queue under Supervisor as Laravel's queue guide describes, set QUEUE_CONNECTION=database in .env, then run sudo -u www-data php artisan optimize and sudo -u www-data php artisan queue:restart from the install folder. If Supervisor owns the workers, also set INTERNAL_QUEUE_ENABLED=false.

Also set an UPDATE_SECRET in .env so strangers cannot trigger the /update?secret= maintenance route.

Getting invoices into your clients' inboxes

Mail is set per company inside the app, under Settings, Email Settings: SMTP, Postmark, Mailgun, Brevo or Amazon SES. Choose Default and the app falls back to the MAIL_* lines in .env. Always fill in a From Email and From Name, or messages are refused as malformed, and press Send Test Email before relying on SMTP. The docs pair port 465 with SSL and 587 with TLS.

Port 25 is open on our dedicated servers and outbound mail is allowed, but invoices land better through a proper relay with SPF and DKIM on your domain. Our guide to business email with your own domain covers those records, and sending app mail when port 25 is closed covers the relay side.

Why a whole machine suits a billing system

Invoice Ninja holds client names, addresses and payment records. On a dedicated server that data sits on one physical computer with no other customer on its processor, memory or disks, and you log in as root to decide what else runs there.

  • No traffic bill. The port is unmetered, so client portal visits, PDF downloads and API calls never add a line to your invoice.
  • A way back in. Rack servers, blades and the m510 and m710x cartridges come with an out-of-band console, the screen and the power button, for the day a firewall rule locks out SSH. The other cartridges have power control only.
  • Start over freely. Reinstall the operating system from the control panel as often as you like; one takes about ten minutes.
  • No contract. Billing is month to month, and the server is handed over within 30 minutes of the order being approved.

The server that fits

For one business, an x86 compact cartridge from the small end of the range is a sensible start, since it has one job to do. If the same box will also carry your website, a CRM or a few more containers, step up to one of the single-processor everyday servers, which is where most apps and databases belong. Each card on the dedicated server list shows the cores, memory, disks, port and cities, and the current price.

Running several self-hosted tools side by side? See containers on bare metal.

Backups and updates without losing history

A restorable Invoice Ninja is three things: the database, the storage folder with uploaded files and logos, and the .env file holding APP_KEY. The docs warn that without that key the application can be left in an invalid state, so keep a copy somewhere other than the server. We do not sell a backup product, so copying all three off the machine on a schedule is your job.

  • Docker: the data lives in the mysql_data, app_storage and app_public volumes. Never run docker compose down -v, which deletes named volumes. To update, take a backup, then run docker compose pull followed by docker compose up -d.
  • Git install: git pull, then composer install -o --no-dev, then php artisan ninja:post-update.
  • Tarball install: the in-app updater needs the folder owned by the web user, the scheduler running and no hidden folders such as .git. Afterwards, visit /update?secret= with your UPDATE_SECRET.
  • Rolling back: set the current folder and a fresh database dump aside first, check both copies exist, and only then replace anything.

Version 4 data does not upgrade in place: v5 starts as a clean install and the data is migrated into it.

When this is the wrong place for it

If you send a handful of invoices a month and do not want to patch a server, a whole machine is more than you need. Our Cloud VPS is a shared virtual machine for small jobs, orderable with Docker installed; Docker Compose on a VPS shows one app behind HTTPS there. Either way, we keep the hardware and network running; the system, Invoice Ninja and its backups are yours.

Questions people ask

Is self-hosting Invoice Ninja free?
The code is published on GitHub and the official Docker images are free to pull. You pay for the server and for any outside mail relay you choose. Taking the Invoice Ninja branding off client-facing pages and PDFs needs a white-label licence bought yearly, and the admin side keeps its branding either way. Sending e-invoices through Invoice Ninja's PEPPOL proxy also needs that licence key in the environment file.
Can I run it on an ARM machine?
Not with the official Docker image: its wiki names Linux x86_64 as the only supported platform, so choose an Intel or AMD server for that route.
Why are my reminder emails not going out?
Almost always the scheduler cron is missing or no queue worker is running. Check that schedule:run fires every minute as the web user, that a worker is alive, and that a From Email is set in Email Settings; storage/logs shows why a message failed.
Do I need Redis?
No. A manual install can queue jobs in the database with QUEUE_CONNECTION=database. The official Docker stack ships Redis and uses it for cache, sessions and the queue.
How quickly can I have a server to install it on?
A ready dedicated server is handed over within 30 minutes of the order being approved, with your chosen operating system installed. Payment and fraud checks come first and are the part that can take longer.

Get a server for your invoicing

A whole machine with root access and an unmetered port, month to month, ready for Docker or a manual Invoice Ninja install.

Choose your server

Read next