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.
| Part | What the docs ask for | What it means for you |
|---|---|---|
| PHP | 8.2 with bcmath, ctype, imagick, soap, gd, mbstring, openssl, tokenizer, xml, curl, zip, gmp, iconv, mysqli, intl, and FPM for nginx | Install them before running setup |
| Database | MySQL 5.7+ or MariaDB 10.3+ | One database and one user with full rights on it |
| Web server | nginx or Apache with HTTPS enabled | Serve a domain or subdomain root; subfolders are not supported |
| Scheduler | A cron entry that runs every minute | Without it, recurring invoices, reminders and exchange-rate updates stall |
| Queue | A worker managed by Supervisor, or a cron worker every 5 minutes | The docs say switching from the default sync mode makes the app faster |
| Updates | 1024M PHP memory_limit for the built-in self-updater | Set 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
- Generate your own encryption key (command below) and copy the whole
base64:...string. The repository's.envcarries a sample key; never reuse it. - Open
.envand setAPP_URLto your real https address,APP_KEYto the key you just made,APP_DEBUG=false, and strong values forDB_PASSWORDandDB_ROOT_PASSWORD. The database is created from these on the very first start, so changing them later will not change the existing database user. - Set
IN_USER_EMAILandIN_PASSWORDto 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. - Keep the plain-HTTP port private. The stack's nginx container publishes port 80 on every address; in
docker-compose.ymlchange it to127.0.0.1:8080:80and[::1]:8080:80, put an HTTPS reverse proxy in front, and setREQUIRE_HTTPS=true. Docker's docs warn that published ports skip ufw rules. - 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
- Install PHP 8.2 with the extensions above, MySQL or MariaDB, and nginx or Apache with a certificate.
- Download
invoiceninja.tarfrom the GitHub releases and unpack it into your vhost, for example/var/www/invoiceninja, with the web server's root pointed at itspublicfolder. - Give the web user ownership:
sudo chown -R www-data:www-data /var/www/invoiceninjaand set folders to 755 withsudo find /var/www/invoiceninja -type d -exec chmod 755 {} \;. Nothing needs 777. - Create the database and a user with full rights on it.
- Add the scheduler to the web user's crontab:
* * * * * cd /var/www/invoiceninja && php artisan schedule:run >> /dev/null 2>&1 - Open
https://your-domain/setupand enter the database details. Do this straight after installing: until the wizard is finished, whoever reaches that page first sets the install up. - Run the queue under Supervisor as Laravel's queue guide describes, set
QUEUE_CONNECTION=databasein.env, then runsudo -u www-data php artisan optimizeandsudo -u www-data php artisan queue:restartfrom the install folder. If Supervisor owns the workers, also setINTERNAL_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_storageandapp_publicvolumes. Never rundocker compose down -v, which deletes named volumes. To update, take a backup, then rundocker compose pullfollowed bydocker compose up -d. - Git install:
git pull, thencomposer install -o --no-dev, thenphp 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 yourUPDATE_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.