Invoice Ninja

Last reviewed Aug 26, 2026 · 796 words

Every Invoice Ninja self-host that goes wrong goes wrong in one of three places: the scheduler is not running, someone regenerated APP_KEY, or PDFs will not render. Get those three right on day one and you have the most complete open-source billing system available, with quotes, recurring invoices, a client portal, time tracking and more payment gateways than you will ever connect. Miss one and the "Medium" difficulty in the catalogue turns into a lost weekend.

The licence is Elastic 2.0, and for most readers that changes nothing

Invoice Ninja is not OSI-approved open source, which is the catalogue's first listed con and worth understanding rather than fearing. The Elastic License 2.0 forbids two things: offering the software to third parties as a managed service, and circumventing the licence-key checks that gate the white-label feature. A freelancer or a 5-person company invoicing its own clients is doing neither. Removing the "powered by Invoice Ninja" footer from client-facing documents is a paid white-label licence, about $30 a year at last check. If the distinction between source-available and open source matters to you as a matter of principle, the licence explainer covers the categories; if it matters only in practice, it does not apply here.

The scheduler runs the business, and the red banner means it

Recurring invoices, payment reminders, late fees, auto-billing and scheduled reports all fire from Laravel's scheduler. If nothing calls php artisan schedule:run every minute, none of them happen, and the admin UI shows a red "cron not running" banner until they do. The official compose from the invoiceninja/dockerfiles repository handles this, but if you assemble your own stack or run on bare metal, add the crontab entry before you create your first recurring invoice:

* * * * * cd /var/www/app && php artisan schedule:run >> /dev/null 2>&1

Confirm it by watching the banner disappear within a couple of minutes, not by assuming.

APP_KEY is part of your backup, not part of your config

APP_KEY is the Laravel encryption key, and Invoice Ninja uses it to encrypt payment gateway credentials and other secrets stored in the database. Generate it once and never again:

docker run --rm invoiceninja/invoiceninja php artisan key:generate --show

Regenerating it on a whim, which is easy to do while fixing an unrelated error, leaves every stored Stripe or PayPal token unreadable. Store the key alongside the nightly MySQL dump; a database restore without the matching key is a database full of ciphertext.

PDFs need Chromium, and Chromium needs RAM

Version 5 renders invoices through headless Chromium (PDF_GENERATOR=snappdf), which the official Docker image bundles. This is where the catalogue's 512 MB minimum becomes a floor rather than a target: idle usage sits comfortably under it, but a render spikes well above, and on a small ARM board the first PDF is a common failure. Give the container 1 GB if you can, and test a PDF download before you send the first quote to a client.

The stack behind the app

The reference deployment is three containers: the app (PHP-FPM), nginx, and MySQL or MariaDB, with the app's storage and public directories on persistent volumes. Set APP_URL to the exact public address, because emailed links and the client portal are built from it, and set TRUSTED_PROXIES when a reverse proxy terminates TLS so that generated links use HTTPS. Outbound email is its own configuration (MAIL_MAILER, MAIL_HOST and friends); a transactional provider costs little and saves you from the self-hosted email rabbit hole for something as delivery-critical as invoices.

Where it sits against the smaller options

Crater does invoices and expenses with a fraction of the setup and a fraction of the features; it wins for a solo freelancer who wants 5 minutes, not an afternoon. Akaunting is accounting-first with invoicing attached, closer to a ledger than a billing engine. Invoice Ninja is the one you choose when you need recurring billing, client logins, and the gateway list of a SaaS product, which is why it appears on the QuickBooks alternatives list rather than only the FreshBooks one.

What I'd do

Run the official three-container compose on a box with at least 2 GB of RAM, behind Caddy with a real domain. Generate APP_KEY once and write it into the same backup job as the database. Send one test recurring invoice to your own address and watch it arrive on schedule before trusting it with a client. Done that way it is the best free billing platform you can own, and the licence footnote will never come up.