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

1. Export clients as CSV from FreshBooks
2. Import to InvoiceNinja: Import → Clients → CSV
3. Export invoices from FreshBooks
4. Import invoices: Import → Invoices → FreshBooks format

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

From QuickBooks

1. QuickBooks export: File → Export → Lists to IIF
2. InvoiceNinja can import clients from CSV; invoices require manual re-entry or the QuickBooks import tool
3. 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)

---

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

Related: Best Open Source Alternatives to Stripe Billing 2026 · How to Self-Host Firefly III — Personal Finance Manager 2026 · Best Open Source Billing and Invoicing Tools in 2026