Finance intermediate ⏱ 45 minutes

Invoice Ninja: Invoicing and Payments

Professional invoicing for freelancers. Quotes, invoices, and payment tracking.

By Homelab Team • 2025-01-15
#invoice-ninja#invoicing#payments#freelance#docker

Introduction

Invoice Ninja is a comprehensive invoicing and payment management platform designed for freelancers, consultants, and small businesses. Unlike basic invoicing tools, Invoice Ninja provides a complete business management solution with client tracking, expense management, time tracking, project management, and integrated payment processing.

With over 8,000 GitHub stars and backing from more than 30,000 businesses worldwide, Invoice Ninja has matured into a production-ready alternative to expensive SaaS platforms like FreshBooks, QuickBooks Online, or Harvest.

What Makes Invoice Ninja Different?

Complete Business Management Suite

Invoice Ninja goes beyond simple invoicing:

  • Professional invoice and quote generation
  • Recurring billing with automated reminders
  • Expense tracking with receipt uploads
  • Time tracking with billable hours
  • Project and task management
  • Client portal for self-service access
  • Multi-currency and multi-language support
  • White-label branding capabilities

Integrated Payment Processing

Accept payments directly through invoices:

  • Stripe integration for credit cards
  • PayPal Express Checkout
  • Authorize.Net, Braintree, WePay
  • Bank transfer (ACH/SEPA) support
  • Cryptocurrency payments (via Coinbase Commerce)
  • Over 50 payment gateways supported

Professional Features

Generate polished, customizable documents:

  • Multiple invoice templates with custom designs
  • Automatic PDF generation and email delivery
  • Multilingual invoices (40+ languages)
  • Custom fields for industry-specific requirements
  • Automated late payment reminders
  • Client statements and reports

Why Self-Host Invoice Ninja?

Data Privacy and Ownership

Your client list, financial records, and business intelligence stay on your infrastructure. Commercial platforms like FreshBooks or QuickBooks own your data and may use it for competitive analysis or marketing purposes.

Cost Savings

SaaS Pricing Comparison:

  • FreshBooks: $17-55/month ($204-660/year)
  • QuickBooks Online: $30-200/month ($360-2,400/year)
  • Harvest: $12-25/month ($144-300/year)
  • Zoho Invoice: Free-$29/month ($0-348/year)

Invoice Ninja Self-Hosted:

  • Software: Free (open source)
  • Hosting: $5-20/month server costs ($60-240/year)
  • Payment processing: Same rates as SaaS (2.9% + $0.30 per transaction)
  • Annual savings: $84-2,160 compared to commercial platforms

Unlimited Everything

SaaS platforms limit clients, invoices, or users based on pricing tiers. Self-hosted Invoice Ninja has no artificial limits:

  • Unlimited clients and invoices
  • Unlimited users (team members)
  • Unlimited projects and tasks
  • No feature restrictions
  • No storage caps

White-Label Capability

Remove all Invoice Ninja branding and add your own:

  • Custom domain (invoices.yourbusiness.com)
  • Your logo and brand colors
  • Custom email templates
  • Personalized client portal
  • Professional credibility without “Powered by” watermarks

Prerequisites

Before deploying Invoice Ninja, ensure you have:

System Requirements

Minimum Configuration:

  • 2 CPU cores
  • 2GB RAM (4GB recommended)
  • 10GB disk space (20GB+ for document storage)
  • Docker 20.10+ and Docker Compose v2.0+

Recommended Configuration:

  • 4 CPU cores
  • 4GB RAM
  • 50GB disk space (SSD for database performance)
  • Reverse proxy with HTTPS (required for payment gateways)
  • Email server or SMTP service (for invoice delivery)

Required Knowledge

  • Docker and containerization basics
  • Basic understanding of web servers and reverse proxies
  • Familiarity with environment variable configuration
  • Basic command line skills
  • Understanding of SSL/TLS certificates (for HTTPS)

Business Preparation

Gather before starting:

  • Business logo and branding assets
  • Client contact information
  • Service/product descriptions and pricing
  • Tax rates and registration numbers
  • Payment gateway API credentials (Stripe, PayPal, etc.)
  • SMTP email server credentials

Understanding Invoice Ninja’s Architecture

Invoice Ninja v5 (current version) uses a modern microservices architecture:

Frontend Layer:

  • React-based admin panel
  • Responsive client portal
  • PDF generator for invoices/quotes
  • Real-time updates via WebSockets

Backend Layer:

  • PHP 8.1+ with Laravel framework
  • RESTful API for all operations
  • Queue system for background jobs
  • Multi-tenant database design

Data Layer:

  • MySQL 8.0+ or MariaDB 10.3+
  • Redis for caching and sessions
  • File storage for receipts and documents

Optional Components:

  • PhantomJS or Chromium for PDF generation
  • Supervisord for queue workers
  • NGINX or Apache web server
  • Let’s Encrypt for SSL certificates

Data Flow:

Client Portal → Frontend (React) → API (Laravel) → Database (MySQL)
                    ↓                    ↓
            PDF Generator         Queue Workers
                    ↓                    ↓
            Document Storage      Email Delivery

Installation with Docker Compose

Step 1: Create Project Directory

# Create directory structure
mkdir -p ~/invoice-ninja
cd ~/invoice-ninja

# Create subdirectories
mkdir -p mysql public storage logs

Step 2: Generate Application Key

Invoice Ninja requires a secure application key:

# Generate 32-character random key
openssl rand -base64 32
# Example output: kSN8VJN6nYqGGb3VqOdw8xQqLZMqd+J2eFKhdC5W1Ns=

Save this key for the next step.

Step 3: Create Environment Configuration

Create .env file:

# Application Settings
APP_NAME="Invoice Ninja"
APP_ENV=production
APP_KEY=base64:kSN8VJN6nYqGGb3VqOdw8xQqLZMqd+J2eFKhdC5W1Ns=
APP_DEBUG=false
APP_URL=https://invoices.yourdomain.com

# Database Configuration
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=ninja
DB_USERNAME=ninja
DB_PASSWORD=your-secure-database-password-here
DB_ROOT_PASSWORD=your-secure-root-password-here

# Database Type
DB_TYPE=mysql

# Mail Configuration (Required for sending invoices)
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD=your-app-specific-password
MAIL_ENCRYPTION=tls
[email protected]
MAIL_FROM_NAME="${APP_NAME}"

# Queue Configuration
QUEUE_CONNECTION=database

# Session and Cache
SESSION_DRIVER=file
CACHE_DRIVER=file

# Redis (Optional - for better performance)
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# PDF Generation
PDF_GENERATOR=snappdf

# Multi-user Configuration
MULTI_DB_ENABLED=false

# Trusted Proxies (if using reverse proxy)
TRUSTED_PROXIES=*

# File Upload Limits
UPLOAD_MAX_FILESIZE=20M
POST_MAX_SIZE=20M

# Payment Gateway API Keys (Add as needed)
STRIPE_API_KEY=
STRIPE_PUBLISHABLE_KEY=
PAYPAL_CLIENT_ID=
PAYPAL_SECRET=

# Optional: Google OAuth for user authentication
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=

Step 4: Create Docker Compose File

Create docker-compose.yml:

version: '3.8'

services:
  mysql:
    image: mariadb:10.11
    container_name: invoice-ninja-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:/var/lib/mysql
    networks:
      - invoice-ninja-network
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  invoice-ninja:
    image: invoiceninja/invoiceninja:5
    container_name: invoice-ninja-app
    restart: unless-stopped
    ports:
      - "8000:80"
    depends_on:
      mysql:
        condition: service_healthy
    env_file:
      - .env
    volumes:
      - ./public:/var/www/app/public
      - ./storage:/var/www/app/storage
      - ./logs:/var/www/app/storage/logs
    networks:
      - invoice-ninja-network
    labels:
      # Traefik configuration (optional)
      - "traefik.enable=true"
      - "traefik.http.routers.invoice-ninja.rule=Host(`invoices.yourdomain.com`)"
      - "traefik.http.routers.invoice-ninja.entrypoints=websecure"
      - "traefik.http.routers.invoice-ninja.tls=true"
      - "traefik.http.routers.invoice-ninja.tls.certresolver=letsencrypt"
      - "traefik.http.services.invoice-ninja.loadbalancer.server.port=80"

networks:
  invoice-ninja-network:
    driver: bridge

volumes:
  mysql:
  public:
  storage:
  logs:

Step 5: Deploy Invoice Ninja

# Start all services
docker compose up -d

# Wait for database initialization
sleep 30

# Check container status
docker compose ps

# View application logs
docker compose logs -f invoice-ninja

# Look for: "Server started successfully"

Step 6: Initial Setup

Navigate to http://YOUR-SERVER-IP:8000/setup in your browser.

Setup Wizard:

  1. Database Check - Should show green checkmarks
  2. Account Setup
    • Email: [email protected]
    • Password: Strong password (16+ characters)
    • First Name, Last Name
  3. Company Information
    • Company Name
    • Company Logo (upload)
    • Address, Phone, Email
    • Tax Number / Business Registration
  4. Email Configuration - Verify SMTP settings work
  5. Complete Setup

You’ll be redirected to the dashboard.

Payment Gateway Configuration

Setting Up Stripe

Stripe is the most popular payment gateway for Invoice Ninja.

Get Stripe API Keys:

  1. Create account at https://stripe.com
  2. Navigate to Developers → API Keys
  3. Copy “Publishable key” and “Secret key”
  4. For testing: Use test mode keys (start with pk_test_ and sk_test_)

Configure in Invoice Ninja:

Settings → Payment Gateways → Add Gateway
├─ Select "Stripe"
├─ Enter Publishable Key
├─ Enter Secret Key
├─ Enable "Credit Card" payment method
├─ Enable "ACH" (bank transfers) if desired
└─ Save

Test Configuration:
├─ Create test invoice
├─ Click "Pay Now" in client portal
├─ Use Stripe test card: 4242 4242 4242 4242
└─ Verify payment processes successfully

Stripe Fees:

  • 2.9% + $0.30 per transaction (US cards)
  • 3.9% + $0.30 for international cards
  • No monthly fees for standard account

Setting Up PayPal

PayPal provides alternative payment option for clients.

Get PayPal Credentials:

  1. Create PayPal Business account
  2. Navigate to Account Settings → API Access
  3. Generate API credentials (NVP/SOAP)
  4. Or use PayPal Express Checkout (easier setup)

Configure in Invoice Ninja:

Settings → Payment Gateways → Add Gateway
├─ Select "PayPal Express"
├─ Enter Client ID
├─ Enter Secret
├─ Choose environment (Sandbox for testing, Live for production)
└─ Save

PayPal Fees:

  • 2.9% + $0.30 per transaction (domestic)
  • 4.4% + fixed fee for international
  • No monthly fees

Setting Up Bank Transfer (Manual)

For clients who prefer direct bank transfers:

Settings → Payment Gateways → Add Gateway
├─ Select "Bank Transfer"
├─ Enter bank account details in instructions:
   "Please transfer to:
   Account Name: Your Business Name
   Account Number: 123456789
   Routing Number: 987654321
   Bank: Your Bank Name
   Reference: Invoice #INVOICE_NUMBER"
└─ Save

Payments must be manually marked as received after bank confirmation.

Setting Up Cryptocurrency Payments

Accept Bitcoin, Ethereum, and other cryptocurrencies:

Using Coinbase Commerce:

  1. Create Coinbase Commerce account
  2. Get API Key from Settings
  3. In Invoice Ninja: 
    Settings → Payment Gateways → Add Gateway
├─ Select "Coinbase"
├─ Enter API Key
└─ Save

Supported Cryptocurrencies:

  • Bitcoin (BTC)
  • Ethereum (ETH)
  • Litecoin (LTC)
  • Bitcoin Cash (BCH)
  • USDC and other stablecoins

Fees: 1% Coinbase Commerce fee

Client Portal and Self-Service

The client portal allows customers to view invoices, make payments, and manage their account.

Enable Client Portal

Settings → Client Portal
├─ Enable Portal: Yes
├─ Portal Domain: invoices.yourdomain.com/client
├─ Allow Registration: Yes/No (your choice)
├─ Require Password: Yes (recommended)
├─ Portal Mode: Domain (for custom branding)
└─ Save

Client Portal Features

What Clients Can Do:

  • View all invoices and quotes
  • Download PDF copies
  • Make payments online
  • View payment history
  • Update contact information
  • View outstanding balance
  • Access recurring invoice schedule
  • Upload documents to projects

White-Label Customization:

Settings → Client Portal → Customize
├─ Header Color: #your-brand-color
├─ Sidebar Color: #your-accent-color
├─ Custom CSS: Add your own styles
├─ Footer Text: Your copyright notice
└─ Remove "Powered by Invoice Ninja" (paid feature in hosted version, free in self-hosted)

Client Registration Workflow

When enabled, clients can self-register:

  1. Client visits portal URL
  2. Clicks “Register”
  3. Enters email and creates password
  4. You receive notification of new registration
  5. Approve/reject registration from admin panel
  6. Client gains access to their invoices

Invoicing Workflow

Creating Your First Invoice

Manual Invoice Creation:

Invoices → Create Invoice

1. Select Client (or create new):
   ├─ Client Name: Acme Corporation
   ├─ Contact Email: [email protected]
   ├─ Phone: (555) 123-4567
   └─ Address: Full billing address

2. Add Line Items:
   ├─ Description: "Website Development"
   ├─ Quantity: 40 hours
   ├─ Rate: $75/hour
   └─ Tax: Apply if required

3. Configure Invoice:
   ├─ Invoice Date: Today
   ├─ Due Date: Net 30 (30 days from issue)
   ├─ Invoice Number: Auto-generated (or custom)
   ├─ PO Number: If client provided
   └─ Notes: Payment terms, thank you message

4. Review and Send:
   ├─ Preview PDF
   ├─ Send Email to client
   └─ Or mark as "Sent" if sending manually

Invoice Email Contains:

  • Personalized message
  • Invoice PDF attachment
  • “View Invoice” button → Opens client portal
  • “Pay Now” button → Direct payment link
  • Company branding

Recurring Invoices

Automate monthly, quarterly, or annual billing:

Recurring Invoices → Create Recurring Invoice

Configuration:
├─ Frequency: Monthly, Quarterly, Annually, Weekly
├─ Start Date: When billing begins
├─ End Date: Optional (leave blank for ongoing)
├─ Auto-bill: Automatically charge payment method on file
├─ Send Email: Automatically email invoice to client
└─ Reminder: Send reminder X days before/after due date

Example: Monthly Subscription Service
├─ Frequency: Monthly
├─ Start: 2025-01-01
├─ Amount: $99/month
├─ Auto-bill: Enabled (charge credit card on file)
└─ Send Email: 3 days before charge

Auto-bill requires:

  • Payment gateway configured (Stripe, PayPal, etc.)
  • Client has payment method saved
  • Client authorized auto-billing

Quotes and Proposals

Create professional quotes that convert to invoices:

Quotes → Create Quote

1. Add items and pricing (same as invoice)
2. Set expiration date (e.g., 30 days)
3. Send to client for approval
4. Client can:
   ├─ Approve quote (converts to invoice)
   ├─ Request changes (you receive notification)
   └─ Decline (you receive notification)
5. Upon approval, invoice automatically created

Invoice Templates and Customization

Select Template:

Settings → Invoice Design
├─ Choose from 10+ built-in templates:
   - Clean
   - Bold
   - Modern
   - Playful
   - Business
   - Creative
└─ Customize colors, fonts, layout

Advanced Customization:

Settings → Invoice Design → Customize Design

Available Options:
├─ Header: Company logo placement and size
├─ Colors: Primary, secondary, accent colors
├─ Fonts: Choose from Google Fonts
├─ Layout: Single column vs. two column
├─ Footer: Custom text, page numbers
├─ Fields: Show/hide specific fields
└─ Custom CSS: Full design control

Expense Tracking and Management

Recording Expenses

Expenses → Create Expense

1. Enter expense details:
   ├─ Vendor: Where you spent money
   ├─ Amount: Total cost
   ├─ Category: Office supplies, travel, etc.
   ├─ Date: When expense occurred
   └─ Payment Method: Cash, credit card, etc.

2. Upload receipt:
   ├─ Take photo with phone
   ├─ Or upload PDF/image
   └─ Stored securely with expense record

3. Link to client/project (if billable):
   ├─ Select client
   ├─ Select project
   ├─ Mark as "Should be invoiced"
   └─ Expense auto-adds to next invoice

Billable Expenses

Convert expenses directly to invoice line items:

Workflow:
1. Record expense, mark as "Should be invoiced"
2. Select associated client
3. Create invoice for that client
4. Click "Add Expenses" button
5. Select which expenses to bill
6. Apply markup if desired (e.g., 15% handling fee)
7. Expenses added as line items automatically

Example:

Expense: Domain registration for client - $15
Markup: 20% ($3)
Invoice line item: "Domain registration" - $18
Your profit: $3
Client billed: $18

Expense Categories

Organize expenses for tax reporting:

Settings → Expense Categories

Default Categories:
├─ Office Supplies
├─ Travel
├─ Meals & Entertainment
├─ Software & Subscriptions
├─ Professional Services
├─ Marketing & Advertising
└─ Equipment

Custom Categories:
Add industry-specific categories as needed

Time Tracking and Projects

Project Setup

Projects → Create Project

1. Project details:
   ├─ Project Name: "Website Redesign"
   ├─ Client: Acme Corporation
   ├─ Due Date: 2025-03-31
   ├─ Budgeted Hours: 120 hours
   └─ Task Rate: $75/hour

2. Add tasks:
   ├─ Design mockups (20 hours)
   ├─ Frontend development (40 hours)
   ├─ Backend development (40 hours)
   └─ Testing and QA (20 hours)

Time Tracking

Manual Time Entry:

Tasks → Select Task → Start Timer
├─ Timer runs in background
├─ Pause/resume as needed
├─ Stop when complete
└─ Time automatically logged

Manual Entry:

Tasks → Add Time
├─ Select task
├─ Enter hours: 2.5
├─ Date: 2025-01-15
├─ Notes: "Completed homepage design"
└─ Save

Billing Time Entries

Convert tracked time to invoice:

1. Invoices → Create Invoice
2. Select client with unbilled time
3. Click "Add Tasks"
4. Select which time entries to bill
5. Review line items:
   ├─ Task: "Frontend development"
   ├─ Hours: 8.5
   ├─ Rate: $75/hour
   └→ Total: $637.50
6. Send invoice

Time Tracking Reports:

Reports → Time
├─ View total hours per client
├─ Billable vs. non-billable breakdown
├─ Time by project
├─ Team member productivity
└─ Export to CSV for analysis

Security Best Practices for Financial Data

Database Security

Enable Encrypted Backups:

#!/bin/bash
# encrypted-backup.sh

# Backup and encrypt database
docker exec invoice-ninja-db mysqldump -u ninja -p${DB_PASSWORD} ninja |   gpg --symmetric --cipher-algo AES256   --output "/backups/invoice-ninja-$(date +%Y%m%d).sql.gpg"

# Remove unencrypted backups
find /backups -name "*.sql" -delete

HTTPS Enforcement

Using Caddy:

invoices.yourdomain.com {
    reverse_proxy localhost:8000
    encode gzip

    # Security headers
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Frame-Options "SAMEORIGIN"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
    }
}

Two-Factor Authentication

Enable 2FA for all user accounts:

Settings → Account Management → Two Factor Authentication
├─ Enable 2FA: Yes
├─ Method: TOTP (Google Authenticator, Authy)
├─ Scan QR code with authenticator app
├─ Enter 6-digit code to verify
└─ Save backup codes securely

User Permissions

Control what team members can access:

Settings → Users → Add User

Permission Levels:
├─ Administrator: Full access
├─ Manager: All features except company settings
├─ Employee: Time tracking, expenses only
└─ Custom: Granular permission control

Granular Permissions:
├─ View Invoices: Yes/No
├─ Create Invoices: Yes/No
├─ Edit Invoices: Yes/No
├─ Delete Invoices: Yes/No
├─ View Payments: Yes/No
├─ Process Payments: Yes/No
└─ Access Reports: Yes/No

API Security

Protect API access for integrations:

Settings → API Tokens

Best Practices:
├─ Create separate token for each integration
├─ Use descriptive names ("Zapier Integration", "Mobile App")
├─ Rotate tokens quarterly
├─ Revoke unused tokens immediately
├─ Monitor API usage in logs
└─ Use IP whitelist if possible

Backup Procedures

Automated Daily Backups

#!/bin/bash
# /usr/local/bin/backup-invoice-ninja.sh

BACKUP_DIR="/backups/invoice-ninja"
DATE=$(date +%Y%m%d-%H%M%S)
RETENTION_DAYS=30

mkdir -p "$BACKUP_DIR"

# Backup database
docker exec invoice-ninja-db mysqldump   -u ninja -p${DB_PASSWORD} ninja |   gzip > "$BACKUP_DIR/database-$DATE.sql.gz"

# Backup files (invoices, receipts, logos)
tar czf "$BACKUP_DIR/files-$DATE.tar.gz"   ~/invoice-ninja/public   ~/invoice-ninja/storage

# Verify backups
if [ -f "$BACKUP_DIR/database-$DATE.sql.gz" ]; then
    echo "✓ Backup successful: $DATE"
    SIZE=$(du -sh "$BACKUP_DIR/database-$DATE.sql.gz" | cut -f1)
    echo "  Database: $SIZE"
else
    echo "✗ Backup FAILED!"
    # Send alert email
    exit 1
fi

# Clean old backups
find "$BACKUP_DIR" -name "*.gz" -mtime +$RETENTION_DAYS -delete

# Optional: Upload to cloud
# rclone copy "$BACKUP_DIR/" remote:invoice-ninja-backups/

Schedule with Cron:

# Daily at 2 AM
0 2 * * * /usr/local/bin/backup-invoice-ninja.sh >> /var/log/invoice-ninja-backup.log 2>&1

Disaster Recovery

Full System Restore:

#!/bin/bash
# restore-invoice-ninja.sh

BACKUP_DATE="20250115-020000"
BACKUP_DIR="/backups/invoice-ninja"

# Stop services
cd ~/invoice-ninja
docker compose down

# Restore database
gunzip < "$BACKUP_DIR/database-$BACKUP_DATE.sql.gz" |   docker exec -i invoice-ninja-db mysql -u ninja -p${DB_PASSWORD} ninja

# Restore files
tar xzf "$BACKUP_DIR/files-$BACKUP_DATE.tar.gz" -C ~/invoice-ninja/

# Fix permissions
sudo chown -R www-data:www-data ~/invoice-ninja/public
sudo chown -R www-data:www-data ~/invoice-ninja/storage

# Restart services
docker compose up -d

echo "Restore complete. Verify at http://YOUR-SERVER-IP:8000"

Data Import from Other Tools

Migrating from FreshBooks

Export from FreshBooks:

1. Settings → Data Export
2. Select "Clients", "Invoices", "Expenses"
3. Choose CSV format
4. Download ZIP file
5. Extract individual CSV files

Import to Invoice Ninja:

Settings → Import/Export → Import Data
├─ Select source: "FreshBooks"
├─ Upload clients.csv
├─ Upload invoices.csv
├─ Upload expenses.csv
├─ Map fields (auto-detected)
└─ Import

Migrating from QuickBooks

Export from QuickBooks:

QuickBooks Online:
1. Reports → Export data
2. Select date range
3. Download as Excel/CSV

QuickBooks Desktop:
1. File → Utilities → Export → Lists to IIF Files
2. Export Customers, Invoices, Items

Import Process:

Convert QuickBooks IIF or CSV to Invoice Ninja format using community tools or manual CSV import.

Migrating from Harvest

Export from Harvest:

1. Time → Export Time
2. Invoices → Export Invoices
3. Clients → Export Clients
4. Download as CSV

Import to Invoice Ninja:

Settings → Import → Select Harvest
Upload each CSV file separately
Review imported data for accuracy

Troubleshooting

Email Not Sending

Test email configuration:

# Access container
docker exec -it invoice-ninja-app /bin/bash

# Test SMTP
php artisan tinker
Mail::raw('Test email from Invoice Ninja', function($msg) {
    $msg->to('[email protected]')->subject('Test');
});

# Check logs
docker compose logs invoice-ninja | grep -i mail

Common SMTP issues:

  • Gmail: Use app-specific password, not account password
  • Port 587 requires TLS encryption
  • Some hosts block outbound port 25
  • Check firewall rules

PDF Generation Fails

Symptoms: Blank PDFs or generation errors

Solutions:

# Check PDF generator
Settings → Invoice Design → PDF Generator
# Try switching between:
# - SnapPDF (default, most compatible)
# - Phantom JS
# - Chromium

# Increase memory limit
# Edit docker-compose.yml
environment:
  - PHP_MEMORY_LIMIT=512M

# Restart container
docker compose restart invoice-ninja

Payment Gateway Errors

Stripe test mode not working:

Verify:
├─ Using test API keys (pk_test_, sk_test_)
├─ Test card: 4242 4242 4242 4242
├─ Any CVV and future expiration date
└─ Webhook configured (if using recurring)

PayPal sandbox issues:

Common causes:
├─ Wrong API credentials (Sandbox vs. Live)
├─ PayPal account not verified
├─ Currency mismatch
└─ Webhook URL not configured

Database Connection Errors

# Check database status
docker compose ps

# View database logs
docker compose logs mysql

# Test connection
docker exec -it invoice-ninja-db mysql -u ninja -p

# Reset database (DESTROYS DATA!)
docker compose down -v
docker compose up -d

Slow Performance

Optimization steps:

# Enable caching
# Edit .env
CACHE_DRIVER=redis
SESSION_DRIVER=redis

# Add Redis to docker-compose.yml
  redis:
    image: redis:alpine
    container_name: invoice-ninja-redis
    restart: unless-stopped
    networks:
      - invoice-ninja-network

# Clear application cache
docker exec invoice-ninja-app php artisan cache:clear
docker exec invoice-ninja-app php artisan config:clear
docker exec invoice-ninja-app php artisan view:clear

# Optimize database
docker exec invoice-ninja-db mysqlcheck -u ninja -p --optimize --all-databases

Conclusion

Invoice Ninja provides a professional, self-hosted invoicing and business management platform that rivals expensive SaaS alternatives. By hosting it yourself, you maintain complete control over your business data while saving hundreds or thousands of dollars annually.

What you’ve accomplished:

  • Deployed professional invoicing platform with payment processing
  • Configured multiple payment gateways for client flexibility
  • Set up secure client portal with white-label branding
  • Implemented automated backup and security best practices
  • Established workflow for invoicing, expenses, and time tracking

Next steps:

  • Import existing clients and historical invoices
  • Configure email templates with your branding
  • Set up recurring invoices for subscription clients
  • Integrate payment gateways and test payment flow
  • Train team members on time tracking and expense submission
  • Create custom invoice templates matching your brand

Additional resources:

  • Official documentation: https://invoiceninja.github.io
  • Community forum: Active support community
  • GitHub: https://github.com/invoiceninja/invoiceninja
  • API documentation: https://api-docs.invoicing.co

With Invoice Ninja running in your homelab, you have a complete business management solution that grows with your needs without increasing costs or sacrificing data privacy. The professional features and integrated payments streamline your billing workflow while maintaining the credibility your clients expect.