# Invoice Ninja

> Invoicing, payments, and expense tracking.

- Category: E-Commerce & Business
- Difficulty: intermediate
- Components: invoice-ninja, mariadb
- Tags: invoice, billing, payments, business
- Source: https://docker.recipes/ecommerce/invoice-ninja

## 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.

## 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

## Use cases

- Freelance consultants managing client billing, time tracking, and expense reimbursements
- Small accounting firms handling invoicing for multiple client businesses with separate books
- Service-based businesses requiring recurring subscription billing with automated payment processing
- Construction companies tracking project expenses, materials costs, and progress billing
- Creative agencies managing retainer agreements, milestone payments, and client approval workflows
- Professional services firms needing detailed time tracking and billable hours reporting
- 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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  invoice_public:
  invoice_storage:
  mariadb_data:

networks:
  invoice:
    driver: bridge
```

## .env

```bash
APP_KEY=base64:generated-key-here
DB_ROOT_PASSWORD=rootpassword
DB_NAME=ninja
DB_USER=ninja
DB_PASSWORD=changeme
```

## Usage notes

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

## 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

