How to Self-Host InvoiceNinja: Open Source Invoicing and Billing in 2026

TL;DR

InvoiceNinja is a full-featured open source invoicing platform — create professional invoices, track payments, manage clients, bill time, and accept online payments via Stripe, PayPal, and 40+ other gateways. Version 5 (built on Flutter + Laravel) is the current major release. Where FreshBooks charges $170+/month for 50 clients and QuickBooks charges $100+/month, InvoiceNinja's self-hosted version is free forever with no client limits. The hosted cloud plan starts at $14/month but self-hosting on a $6/month VPS gives you everything for essentially free.

Key Takeaways

Free to self-host: unlimited clients, invoices, and users on self-hosted
Payment gateways: Stripe, PayPal, Square, Braintree, Authorize.net, and 40+ more
Client portal: clients log in, view invoices, download statements, pay online
Recurring invoices: auto-generate and send invoices on any schedule
Time tracking: built-in timer, link billable hours directly to invoices
Multi-currency: 160+ currencies, custom exchange rates
GitHub stars: 8,000+ for InvoiceNinja v5
License: Elastic License 2.0 (source-available) for v5; earlier versions were true open source

What InvoiceNinja Replaces

Feature	FreshBooks	QuickBooks	InvoiceNinja (Self-Hosted)
Price	$170/mo (50 clients)	$100/mo	$6/mo (VPS)
Client limit	Plan-based	Unlimited	Unlimited
Invoicing	✅	✅	✅
Time tracking	✅	Limited	✅
Expense tracking	✅	✅	✅
Client portal	✅	✅	✅
Online payments	✅	✅	✅ (40+ gateways)
Data location	FreshBooks' cloud	Intuit's cloud	Your server

Self-Hosting with Docker Compose

Prerequisites

Server with 1GB RAM minimum (2GB recommended)
Domain with SSL certificate
Docker and Docker Compose

docker-compose.yml

version: '3.7'

services:
  app:
    image: invoiceninja/invoiceninja:5
    container_name: invoiceninja-app
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./storage:/var/www/app/storage
      - ./public:/var/www/app/public
    depends_on:
      - db
    networks:
      - invoiceninja

  nginx:
    image: nginx:alpine
    container_name: invoiceninja-nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./public:/var/www/app/public:ro
      - ./letsencrypt:/etc/letsencrypt:ro
    depends_on:
      - app
    networks:
      - invoiceninja

  db:
    image: mysql:8.0
    container_name: invoiceninja-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: ${DB_DATABASE}
      MYSQL_USER: ${DB_USERNAME}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - invoiceninja

networks:
  invoiceninja:

volumes:
  mysql_data:

.env Configuration

# .env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://invoices.yourdomain.com
APP_KEY=                    # Generate: php artisan key:generate (or use base64:...)

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=invoiceninja
DB_USERNAME=ninja
DB_PASSWORD=change-this-db-password
DB_ROOT_PASSWORD=change-this-root-password

MAIL_MAILER=smtp
MAIL_HOST=smtp.youremail.com
MAIL_PORT=587
MAIL_USERNAME=invoices@yourdomain.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=invoices@yourdomain.com
MAIL_FROM_NAME="YourCompany Invoices"

# Storage (local by default; can use S3)
FILESYSTEM_DRIVER=local

Generate the APP_KEY:

docker compose run --rm app php artisan key:generate --show
# Copy the output (e.g., base64:xxxx) into APP_KEY in .env

Start and Initialize

docker compose up -d

# Run migrations and seed
docker compose exec app php artisan migrate --force
docker compose exec app php artisan db:seed --class=UserSeeder

# Create your admin account
docker compose exec app php artisan ninja:create-account \
  --email=admin@yourcompany.com \
  --password=your-password

# Access at https://invoices.yourdomain.com

Nginx Configuration with SSL

# nginx/nginx.conf
server {
    listen 80;
    server_name invoices.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name invoices.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/invoices.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/invoices.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    root /var/www/app/public;
    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 300;
    }

    # Block access to sensitive files
    location ~ /\.ht { deny all; }
    location ~ /storage { deny all; }
}

# Get SSL certificate
docker run --rm -v ./letsencrypt:/etc/letsencrypt \
  certbot/certbot certonly --standalone \
  -d invoices.yourdomain.com \
  --email admin@yourcompany.com --agree-tos

Configuring Stripe Payments

Enable online payments so clients can pay invoices with a card:

Settings → Payment Gateways → Add Gateway → Stripe
→ Enter your Stripe Secret Key and Publishable Key
→ Enable: Credit Card, ACH (US bank transfers)
→ Enable 3D Secure (for EU clients)
→ Save

Now when you send an invoice, the email includes a "Pay Now" button. Clicking it opens the client portal with Stripe's card form. Payment status syncs automatically.

Stripe Webhook Setup

In Stripe Dashboard → Webhooks → Add endpoint:
URL: https://invoices.yourdomain.com/stripe/webhook
Events: payment_intent.succeeded, payment_intent.payment_failed

In InvoiceNinja → Settings → Payment Gateways → Stripe:
Webhook Secret: (paste from Stripe)

Setting Up Recurring Invoices

For subscription clients or retainer agreements:

Clients → Select client → New Recurring Invoice
→ Items: Monthly retainer — $3,000
→ Frequency: Monthly (or weekly, quarterly, annual)
→ Start date: 2026-04-01
→ Auto-send: On (emails client automatically)
→ Auto-bill: On (charges saved card automatically)

InvoiceNinja's cron job generates and sends recurring invoices on schedule. Set up the cron:

# Add to crontab on host
docker compose exec app php artisan schedule:run
# Or add to host cron:
* * * * * cd /opt/invoiceninja && docker compose exec -T app php artisan schedule:run >> /dev/null 2>&1

Client Portal

The client portal gives your clients a self-service interface to:

View all invoices (paid, overdue, draft)
Download PDF invoices and statements
Pay outstanding invoices online
View expense reports
Submit project change requests

Customize the portal URL:

Settings → Client Portal
Portal URL: https://invoices.yourdomain.com/client/
Custom CSS: (add your brand colors)
Logo: (upload your company logo)
Primary Color: #your-brand-color

Backup and Restore

#!/bin/bash
# backup-invoiceninja.sh
DATE=$(date +%Y%m%d_%H%M)

# Database backup
docker compose exec -T db mysqldump \
  -u${DB_USERNAME} -p${DB_PASSWORD} ${DB_DATABASE} \
  | gzip > /backups/invoiceninja/db_${DATE}.sql.gz

# File storage backup (uploaded documents, logo, etc.)
tar -czf /backups/invoiceninja/storage_${DATE}.tar.gz ./storage/

# Upload to Backblaze B2
rclone copy /backups/invoiceninja b2:my-backups/invoiceninja/

# Keep only last 30 days locally
find /backups/invoiceninja -type f -mtime +30 -delete

echo "InvoiceNinja backup complete: $DATE"

Restore

# Restore database
gunzip < /backups/invoiceninja/db_20260301.sql.gz | \
  docker compose exec -T db mysql \
  -u${DB_USERNAME} -p${DB_PASSWORD} ${DB_DATABASE}

# Restore storage
tar -xzf /backups/invoiceninja/storage_20260301.tar.gz -C ./

Time Tracking and Project Billing

InvoiceNinja includes a built-in time tracker for billable hours:

Tasks → New Task
→ Client: Acme Corp
→ Project: Website Redesign
→ Description: "Homepage mockup review and revisions"
→ Rate: $150/hour
→ Start timer (or enter hours manually)

When ready to bill:

Tasks → Select completed tasks → Invoice Tasks
→ Creates a new invoice automatically with all billable hours
→ Shows itemized line items: "4.5 hours × $150 = $675"

For ongoing projects, link tasks to a project and generate invoices on demand or on a schedule. The project dashboard shows budgeted hours vs actual hours, keeping you aware of scope creep before it becomes a problem.

Invoice Customization and Templates

InvoiceNinja supports fully customizable invoice templates:

Settings → Invoice Design
→ Choose from 10+ built-in templates
→ Customize:
  - Logo placement
  - Color scheme (match your brand)
  - Font selection
  - Custom fields (add VAT number, PO number, etc.)
  - Footer text (payment terms, bank details)
  - Custom CSS for advanced styling

Multi-Language Invoices

For international clients, InvoiceNinja generates invoices in the client's language:

Clients → Edit client → Settings
→ Language: French / German / Spanish / Japanese / etc.
→ Currency: EUR / GBP / JPY
→ Date Format: DD/MM/YYYY (European format)

When you send an invoice to this client, it renders in their language and currency. Tax labels adjust accordingly (VAT for EU clients, GST for Australian clients, etc.).

Email Customization and Automation

Customize the emails InvoiceNinja sends:

Settings → Email Settings
→ Email Templates:
  - Invoice: "Hi {{client.name}}, your invoice #{{invoice.number}} for ${{invoice.amount}} is ready."
  - Payment confirmation: "Thank you for your payment of ${{payment.amount}}."
  - Overdue reminder: "Invoice #{{invoice.number}} is {{invoice.days_overdue}} days overdue."

Set up automatic payment reminders:

Settings → Payment Reminders
→ First reminder: 3 days before due date
→ Second reminder: 1 day after due date
→ Third reminder: 7 days after due date
→ Final notice: 30 days after due date (with late fee applied)

Apply late fees automatically:

Settings → Late Fees
→ Fee type: Percentage
→ Fee amount: 1.5%
→ Applied: 30 days after due date

Expense Tracking

Track business expenses and mark them as billable to clients:

Expenses → New Expense
→ Vendor: AWS
→ Amount: $245.30
→ Category: Cloud Infrastructure
→ Client: Acme Corp (billable expense)
→ Attach receipt (PDF or image)
→ Mark as invoiced: No (pending)

When billing the client:

Invoices → New Invoice → Add Expense
→ Select the Acme Corp AWS expense
→ Shows as: "Cloud infrastructure reimbursement — $245.30"

Expense reports export to CSV for accountants or QuickBooks import.

API Integration

InvoiceNinja has a full REST API for integration with your own systems:

# List clients
curl -X GET https://invoices.yourdomain.com/api/v1/clients \
  -H "X-Api-Token: your-api-token" \
  -H "Content-Type: application/json"

# Create an invoice programmatically
curl -X POST https://invoices.yourdomain.com/api/v1/invoices \
  -H "X-Api-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "CLIENT_HASH_ID",
    "line_items": [{
      "product_key": "Consulting",
      "notes": "October consulting services",
      "cost": 150,
      "qty": 40
    }],
    "due_date": "2026-11-30",
    "auto_bill_enabled": false
  }'

Use the API to integrate InvoiceNinja with your CRM, project management tool, or custom billing logic. Zapier also has a native InvoiceNinja integration for no-code workflows.

Migrating to InvoiceNinja

From FreshBooks

Export clients as CSV from FreshBooks
Import to InvoiceNinja: Import → Clients → CSV
Export invoices from FreshBooks
Import invoices: Import → Invoices → FreshBooks format

InvoiceNinja supports direct FreshBooks import format — no spreadsheet manipulation needed.

From QuickBooks

QuickBooks export: File → Export → Lists to IIF
InvoiceNinja can import clients from CSV; invoices require manual re-entry or the QuickBooks import tool
Historical data can be entered as opening balances

Upgrading InvoiceNinja

cd /opt/invoiceninja

# Pull latest image
docker compose pull app

# Restart with new image
docker compose up -d app

# Run any new migrations
docker compose exec app php artisan migrate --force

# Check logs for issues
docker compose logs -f app

InvoiceNinja maintains backward-compatible database migrations, but always back up before upgrading minor versions. Major version upgrades (v4 to v5) required a full data migration — the team provided migration tools for this.

Methodology

GitHub data from github.com/invoiceninja/invoiceninja, March 2026
Pricing comparisons from FreshBooks, QuickBooks pricing pages, March 2026
Setup based on InvoiceNinja v5 official documentation (invoiceninja.github.io)
Version: InvoiceNinja v5.x (check GitHub releases for latest)

Why Self-Host InvoiceNinja?

The case for self-hosting InvoiceNinja comes down to three practical factors: data ownership, cost at scale, and operational control.

Data ownership is the fundamental argument. When you use a SaaS version of any tool, your data lives on someone else's infrastructure subject to their terms of service, their security practices, and their business continuity. If the vendor raises prices, gets acquired, changes API limits, or shuts down, you're left scrambling. Self-hosting InvoiceNinja means your data and configuration stay on infrastructure you control — whether that's a VPS, a bare metal server, or a home lab.

Cost at scale matters once you move beyond individual use. Most SaaS equivalents charge per user or per data volume. A self-hosted instance on a $10-20/month VPS typically costs less than per-user SaaS pricing for teams of five or more — and the cost doesn't scale linearly with usage. One well-configured server handles dozens of users for a flat monthly fee.

Operational control is the third factor. The Docker Compose configuration above exposes every setting that commercial equivalents often hide behind enterprise plans: custom networking, environment variables, storage backends, and authentication integrations. You decide when to update, how to configure backups, and what access controls to apply.

The honest tradeoff: you're responsible for updates, backups, and availability. For teams running any production workloads, this is familiar territory. For individuals, the learning curve is real but the tooling (Docker, Caddy, automated backups) is well-documented and widely supported.

Server Requirements and Sizing

Before deploying InvoiceNinja, assess your server capacity against expected workload.

Minimum viable setup: A 1 vCPU, 1GB RAM VPS with 20GB SSD is sufficient for personal use or small teams. Most consumer VPS providers — Hetzner, DigitalOcean, Linode, Vultr — offer machines in this range for $5-10/month. Hetzner offers excellent price-to-performance for European and US regions.

Recommended production setup: 2 vCPUs with 4GB RAM and 40GB SSD handles most medium deployments without resource contention. This gives InvoiceNinja headroom for background tasks, caching, and concurrent users while leaving capacity for other services on the same host.

Storage planning: The Docker volumes in this docker-compose.yml store all persistent InvoiceNinja data. Estimate your storage growth rate early — for data-intensive tools, budget for 3-5x your initial estimate. Hetzner Cloud and Vultr both support online volume resizing without stopping your instance.

Operating system: Any modern 64-bit Linux distribution works. Ubuntu 22.04 LTS and Debian 12 are the most commonly tested configurations. Ensure Docker Engine 24.0+ and Docker Compose v2 are installed — verify with docker --version and docker compose version. Avoid Docker Desktop on production Linux servers; it adds virtualization overhead and behaves differently from Docker Engine in ways that cause subtle networking issues.

Network: Only ports 80 and 443 need to be publicly accessible when running behind a reverse proxy. Internal service ports should be bound to localhost only. A minimal UFW firewall that blocks all inbound traffic except SSH, HTTP, and HTTPS is the single most effective security measure for a self-hosted server.

Backup and Disaster Recovery

Running InvoiceNinja without a tested backup strategy is an unacceptable availability risk. Docker volumes are not automatically backed up — if you delete a volume or the host fails, data is gone with no recovery path.

What to back up: The named Docker volumes containing InvoiceNinja's data (database files, user uploads, application state), your docker-compose.yml and any customized configuration files, and .env files containing secrets.

Backup approach: For simple setups, stop the container, archive the volume contents, then restart. For production environments where stopping causes disruption, use filesystem snapshots or database dump commands (PostgreSQL pg_dump, SQLite .backup, MySQL mysqldump) that produce consistent backups without downtime.

For a complete automated backup workflow that ships snapshots to S3-compatible object storage, see the Restic + Rclone backup guide. Restic handles deduplication and encryption; Rclone handles multi-destination uploads. The same setup works for any Docker volume.

Backup cadence: Daily backups to remote storage are a reasonable baseline for actively used tools. Use a 30-day retention window minimum — long enough to recover from mistakes discovered weeks later. For critical data, extend to 90 days and use a secondary destination.

Restore testing: A backup that has never been restored is a backup you cannot trust. Once a month, restore your InvoiceNinja backup to a separate Docker Compose stack on different ports and verify the data is intact. This catches silent backup failures, script errors, and volume permission issues before they matter in a real recovery.

Security Hardening

Self-hosting means you are responsible for InvoiceNinja's security posture. The Docker Compose setup provides a functional base; production deployments need additional hardening.

Always use a reverse proxy: Never expose InvoiceNinja's internal port directly to the internet. The docker-compose.yml binds to localhost; Caddy or Nginx provides HTTPS termination. Direct HTTP access transmits credentials in plaintext. A reverse proxy also centralizes TLS management, rate limiting, and access logging.

Strong credentials: Change default passwords immediately after first login. For secrets in docker-compose environment variables, generate random values with openssl rand -base64 32 rather than reusing existing passwords.

Firewall configuration:

ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Internal service ports (databases, admin panels, internal APIs) should only be reachable from localhost or the Docker network, never directly from the internet.

Network isolation: Docker Compose named networks keep InvoiceNinja's services isolated from other containers on the same host. Database containers should not share networks with containers that don't need direct database access.

VPN access for sensitive services: For internal-only tools, restricting access to a VPN adds a strong second layer. Headscale is an open source Tailscale control server that puts your self-hosted stack behind a WireGuard mesh, eliminating public internet exposure for internal tools.

Update discipline: Subscribe to InvoiceNinja's GitHub releases page to receive security advisory notifications. Schedule a monthly maintenance window to pull updated images. Running outdated container images is the most common cause of self-hosted service compromises.

Troubleshooting Common Issues

Container exits immediately or won't start

Check logs first — they almost always explain the failure:

docker compose logs -f invoicing

Common causes: a missing required environment variable, a port already in use, or a volume permission error. Port conflicts appear as bind: address already in use. Find the conflicting process with ss -tlpn | grep PORT and either stop it or change InvoiceNinja's port mapping in docker-compose.yml.

Cannot reach the web interface

Work through this checklist:

Confirm the container is running: docker compose ps
Test locally on the server: curl -I http://localhost:PORT
If local access works but external doesn't, check your firewall: ufw status
If using a reverse proxy, verify it's running and the config is valid: caddy validate --config /etc/caddy/Caddyfile

Permission errors on volume mounts

Some containers run as a non-root user. If the Docker volume is owned by root, the container process cannot write to it. Find the volume's host path with docker volume inspect VOLUME_NAME, check the tool's documentation for its expected UID, and apply correct ownership:

chown -R 1000:1000 /var/lib/docker/volumes/your_volume/_data

High resource usage over time

Memory or CPU growing continuously usually indicates unconfigured log rotation, an unbound cache, or accumulated data needing pruning. Check current usage with docker stats invoicing. Add resource limits in docker-compose.yml to prevent one container from starving others. For ongoing visibility into resource trends, deploy Prometheus + Grafana or Netdata.

Data disappears after container restart

Data stored in the container's writable layer — rather than a named volume — is lost when the container is removed or recreated. This happens when the volume mount path in docker-compose.yml doesn't match where the application writes data. Verify mount paths against the tool's documentation and correct the mapping. Named volumes persist across container removal; only docker compose down -v deletes them.

Keeping InvoiceNinja Updated

InvoiceNinja follows a regular release cadence. Staying current matters for security patches and compatibility. The update process with Docker Compose is straightforward:

docker compose pull          # Download updated images
docker compose up -d         # Restart with new images
docker image prune -f        # Remove old image layers (optional)

Read the changelog before major version updates. Some releases include database migrations or breaking configuration changes. For major version bumps, test in a staging environment first — run a copy of the service on different ports with the same volume data to validate the migration before touching production.

Version pinning: For stability, pin to a specific image tag in docker-compose.yml instead of latest. Update deliberately after reviewing the changelog. This trades automatic patch delivery for predictable behavior — the right call for business-critical services.

Post-update verification: After updating, confirm InvoiceNinja is functioning correctly. Most services expose a /health endpoint that returns HTTP 200 — curl it from the server or monitor it with your uptime tool.

Compare open source invoicing tools on OSSAlt — self-hosting complexity, feature coverage, and community activity.

Self-Host InvoiceNinja: Open Source Invoicing 2026