Invoice Ninja

intermediate

Invoicing, payments, and expense tracking.

[i]Overview

Invoice Ninja is a comprehensive open-source invoicing and payment platform that helps businesses streamline their billing operations. Built with PHP and Laravel, it offers a complete suite of financial management tools including invoice generation, payment processing, expense tracking, and client management. The platform supports over 40 payment gateways and provides both self-hosted and cloud-based deployment options, making it ideal for businesses seeking control over their financial data. This stack combines Invoice Ninja with MariaDB to create a robust, self-hosted billing solution. MariaDB serves as the primary data store, leveraging its enhanced performance features and MySQL compatibility to handle invoice data, client records, payment transactions, and expense tracking. The combination provides better performance than standard MySQL setups, particularly for businesses processing high volumes of invoices and payments. Small to medium businesses, freelancers, and accounting firms benefit most from this deployment. The self-hosted nature ensures sensitive financial data remains under your control while providing enterprise-level features like recurring billing, multi-company support, and comprehensive reporting. The MariaDB backend ensures reliable data persistence and supports the complex queries needed for financial reporting and analytics.

[*]Key Features

[+]Complete invoicing workflow with customizable templates, recurring billing, and automated payment reminders
[+]Multi-gateway payment processing supporting Stripe, PayPal, Square, Authorize.net, and 40+ other providers
[+]Client portal allowing customers to view invoices, make payments, and download receipts independently
[+]Expense tracking with receipt uploads, vendor management, and project-based cost allocation
[+]Time tracking integration with project management and billable hours calculation
[+]MariaDB's Aria storage engine providing crash-safe tables with faster recovery than MySQL MyISAM
[+]Advanced reporting with profit/loss statements, aging reports, and tax summaries using MariaDB's enhanced JSON functions
[+]Multi-company support allowing separate books and client bases within a single installation

[#]Common Use Cases

[1]Freelance consultants managing client billing, time tracking, and expense reimbursements
[2]Small accounting firms handling invoicing for multiple client businesses with separate books
[3]Service-based businesses requiring recurring subscription billing with automated payment processing
[4]Construction companies tracking project expenses, materials costs, and progress billing
[5]Creative agencies managing retainer agreements, milestone payments, and client approval workflows
[6]Professional services firms needing detailed time tracking and billable hours reporting
[7]E-commerce businesses requiring integration between sales platforms and financial record-keeping

[!]Prerequisites

[!]Minimum 1GB RAM recommended for MariaDB performance with invoice and payment data
[!]Port 8080 available for Invoice Ninja web interface access
[!]OpenSSL installed for generating the required APP_KEY encryption key
[!]Basic understanding of payment gateway configuration and API credentials
[!]Knowledge of invoice workflow requirements and tax compliance for your jurisdiction
[!]Email server configuration for sending invoice notifications and payment receipts

[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]

1services: 
2  invoice-ninja: 
3    image: invoiceninja/invoiceninja:latest
4    container_name: invoice-ninja
5    restart: unless-stopped
6    environment: 
7      APP_URL: http://localhost:8080
8      APP_KEY: ${APP_KEY}
9      DB_HOST: mariadb
10      DB_DATABASE: ${DB_NAME}
11      DB_USERNAME: ${DB_USER}
12      DB_PASSWORD: ${DB_PASSWORD}
13    volumes: 
14      - invoice_public:/var/www/app/public
15      - invoice_storage:/var/www/app/storage
16    ports: 
17      - "8080:80"
18    depends_on: 
19      - mariadb
20    networks: 
21      - invoice
22
23  mariadb: 
24    image: mariadb:11
25    container_name: invoice-mariadb
26    environment: 
27      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
28      MARIADB_DATABASE: ${DB_NAME}
29      MARIADB_USER: ${DB_USER}
30      MARIADB_PASSWORD: ${DB_PASSWORD}
31    volumes: 
32      - mariadb_data:/var/lib/mysql
33    networks: 
34      - invoice
35
36volumes: 
37  invoice_public: 
38  invoice_storage: 
39  mariadb_data: 
40
41networks: 
42  invoice: 
43    driver: bridge

[$].env Template

[.env]

1APP_KEY=base64:generated-key-here
2DB_ROOT_PASSWORD=rootpassword
3DB_NAME=ninja
4DB_USER=ninja
5DB_PASSWORD=changeme

[i]Usage Notes

[1]Docs: https://invoiceninja.github.io/
[2]Access at http://localhost:8080 - create admin account on first visit
[3]Generate APP_KEY: echo 'base64:'$(openssl rand -base64 32)
[4]Features: invoicing, quotes, payments, expenses, projects, tasks
[5]Client portal for customers to view/pay invoices
[6]Integrates with Stripe, PayPal, Square, and 40+ gateways

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

invoice-ninja

invoice-ninja:
  image: invoiceninja/invoiceninja:latest
  container_name: invoice-ninja
  restart: unless-stopped
  environment:
    APP_URL: http://localhost:8080
    APP_KEY: ${APP_KEY}
    DB_HOST: mariadb
    DB_DATABASE: ${DB_NAME}
    DB_USERNAME: ${DB_USER}
    DB_PASSWORD: ${DB_PASSWORD}
  volumes:
    - invoice_public:/var/www/app/public
    - invoice_storage:/var/www/app/storage
  ports:
    - "8080:80"
  depends_on:
    - mariadb
  networks:
    - invoice

mariadb

mariadb:
  image: mariadb:11
  container_name: invoice-mariadb
  environment:
    MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    MARIADB_DATABASE: ${DB_NAME}
    MARIADB_USER: ${DB_USER}
    MARIADB_PASSWORD: ${DB_PASSWORD}
  volumes:
    - mariadb_data:/var/lib/mysql
  networks:
    - invoice

[>]Quick Start

[terminal]

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  invoice-ninja:
5    image: invoiceninja/invoiceninja:latest
6    container_name: invoice-ninja
7    restart: unless-stopped
8    environment:
9      APP_URL: http://localhost:8080
10      APP_KEY: ${APP_KEY}
11      DB_HOST: mariadb
12      DB_DATABASE: ${DB_NAME}
13      DB_USERNAME: ${DB_USER}
14      DB_PASSWORD: ${DB_PASSWORD}
15    volumes:
16      - invoice_public:/var/www/app/public
17      - invoice_storage:/var/www/app/storage
18    ports:
19      - "8080:80"
20    depends_on:
21      - mariadb
22    networks:
23      - invoice
24
25  mariadb:
26    image: mariadb:11
27    container_name: invoice-mariadb
28    environment:
29      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
30      MARIADB_DATABASE: ${DB_NAME}
31      MARIADB_USER: ${DB_USER}
32      MARIADB_PASSWORD: ${DB_PASSWORD}
33    volumes:
34      - mariadb_data:/var/lib/mysql
35    networks:
36      - invoice
37
38volumes:
39  invoice_public:
40  invoice_storage:
41  mariadb_data:
42
43networks:
44  invoice:
45    driver: bridge
46EOF
47
48# 2. Create the .env file
49cat > .env << 'EOF'
50APP_KEY=base64:generated-key-here
51DB_ROOT_PASSWORD=rootpassword
52DB_NAME=ninja
53DB_USER=ninja
54DB_PASSWORD=changeme
55EOF
56
57# 3. Start the services
58docker compose up -d
59
60# 4. View logs
61docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]

1curl -fsSL https://docker.recipes/api/recipes/invoice-ninja/run | bash

[?]Troubleshooting

[!]Application Error 500 on startup: Verify APP_KEY is properly generated and formatted with 'base64:' prefix
[!]Database connection refused: Check MariaDB container startup order and ensure depends_on is configured correctly
[!]Invoice templates not loading: Confirm invoice_public volume has proper write permissions for the web server
[!]Payment gateway webhook failures: Ensure APP_URL environment variable matches your actual domain, not localhost
[!]PDF generation errors: Verify invoice_storage volume has sufficient space and write permissions for temporary files
[!]Email notifications not sending: Check Invoice Ninja email configuration and ensure SMTP credentials are properly set in admin panel

Community Notes

Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

invoice-ninjamariadb

## Tags

#invoice#billing#payments#business

## Category

E-Commerce & Business

## Related

Shortcuts: C CopyF FavoriteD Download