How to Install Invoice Ninja v5 on Debian 12

Invoice Ninja v5 on Debian 12

Invoice Ninja v5 is a modern, open-source invoicing, billing, and payment management platform built for freelancers, agencies, and small to medium-sized businesses. It allows you to create professional invoices and quotes, manage clients and products, track payments and expenses, and automate recurring billing, all from a clean, web-based interface.

Unlike cloud-only invoicing services, Invoice Ninja can be fully self-hosted, which means you retain complete control over your financial data, client records, and business logic. This makes it an excellent solution for organizations that prioritize data ownership, privacy, compliance, and predictable long-term costs.

Running Invoice Ninja v5 on Debian 12 (Bookworm) provides a rock-solid, security-focused, and long-term supported operating system. Debian 12 includes OpenSSL 3, systemd 252, and a mature PHP ecosystem, making it a reliable foundation for a production-grade invoicing and billing system.

Architecture Overview

Layer	Component	Role
OS	Debian 12 (Bookworm)	Stable, long-term supported Linux base
Web Server	Nginx or Apache	Serves the Invoice Ninja application
Runtime	PHP 8.4 (PHP-FPM)	Executes backend logic (Laravel)
Database	MariaDB / MySQL	Stores invoices, clients, payments, settings
Application	Invoice Ninja v5	Invoicing, billing, reporting engine
TLS	Let’s Encrypt / PKI	Encrypted HTTPS access
Payments	Stripe, PayPal, others	Online payment processing

Invoice Ninja v5 is built on Laravel, offering a clean architecture, strong security practices, and long-term maintainability.

Why Use Invoice Ninja?

Open-source & self-hosted – no vendor lock-in
Professional invoices & quotes – fully customizable templates
Recurring invoices & subscriptions – automate repeat billing
Online payments – Stripe, PayPal, and other gateways
Client portal – clients can view, download, and pay invoices
Expense tracking – monitor operational costs
Multi-currency & tax support – ideal for international businesses
Multi-company support – manage multiple businesses in one instance
REST API – integrate with CRMs, ERPs, and custom systems

Invoice Ninja is ideal for users who want enterprise-level invoicing features without SaaS limitations or monthly fees.

Invoice Ninja vs Other Invoicing Platforms

Feature / Capability	Invoice Ninja	FreshBooks	QuickBooks	Zoho Invoice
Hosting	Self-hosted	Cloud only	Cloud only	Cloud only
Open-source	✅ Yes	❌ No	❌ No	❌ No
Data ownership	Full control	Vendor-controlled	Vendor-controlled	Vendor-controlled
Recurring invoices	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Online payments	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Cost	Free (self-hosted)	Paid	Paid	Free / Paid

Invoice Ninja stands out for flexibility, transparency, and complete control over financial data.

Security & Best Practices on Debian 12

Serve Invoice Ninja only over HTTPS.
Use PHP-FPM with a dedicated pool for isolation and performance.
Restrict database access to localhost or internal networks.
Store secrets (APP_KEY, DB credentials, mail passwords) only in .env.
Set correct file permissions for storage/ and bootstrap/cache/.
Use UFW or nftables and allow only ports 80 and 443.
Configure cron jobs for recurring invoices and background tasks.
Regularly update:
- Debian system packages
- PHP extensions
- Invoice Ninja core
Back up:
- Database
- .env file
- Uploaded assets and generated PDFs
Restrict admin access and enable strong passwords and 2FA where possible.

Typical Use Cases

Freelancers issuing invoices and tracking payments
Agencies managing recurring client billing
Small businesses replacing SaaS invoicing tools
Consultants billing hourly or per project
International companies using multiple currencies and tax rules
Self-hosted business stacks integrated with CRM or ERP systems

Deploying Invoice Ninja v5 on Debian 12 gives you a professional, secure, and fully self-hosted invoicing platform — combining Laravel’s modern architecture with Debian’s legendary stability and full ownership of your financial data.

Step 1: Create a Server Instance on Shape.Host

Invoice Ninja requires a stable Linux server with full root access.

Click Create → Instance

Choose a nearby data center for better latency

Shape.host instance form with the data center location selector highlighted.

Select a plan with at least:

2 CPU cores

4 GB RAM

40 GB SSD

Choose Debian 12 (Bookworm)

Shape.host instance form with the operating system image selector highlighted.

Create the instance and wait for provisioning to complete.

Shape.host instance form with the Create Instance button highlighted.

Copy the public IP address

Shape.host Resources dashboard with the server IP address highlighted.

Step 2: Connect to the Server

Linux / macOS / Windows

ssh root@YOUR_SERVER_IP

This opens a secure shell session and gives you full administrative access to the server.

Step 3: Update the Operating System

apt update

Downloads the latest package lists from Debian repositories
Ensures your system knows about the newest available versions

apt upgrade -y

Installs all available updates
Keeps the system secure and compatible with modern software

Terminal showing APT package management commands and output.

Step 4: Install Apache Web Server

apt install apache2

Installs the Apache HTTP server, which will serve Invoice Ninja

systemctl enable apache2

Configures Apache to start automatically on boot

systemctl start apache2

Starts the Apache service immediately

Apache will handle HTTP/HTTPS traffic and communicate with PHP via PHP-FPM.

Terminal showing systemd service management commands or output.

Step 5: Install and Secure MariaDB

apt install mariadb-server mariadb-client

Installs the database server and client tools

Terminal showing PM2 application process management output.

systemctl enable mariadb

Enables MariaDB at system startup

systemctl start mariadb

Starts the database service

Secure the database

mysql_secure_installation

This interactive script:

Sets a root password
Removes anonymous users
Disables remote root login
Removes test databases

Terminal showing mariadb commands or output during Secure the database.

Create Invoice Ninja database

mysql -u root -p

Inside MariaDB:

CREATE DATABASE invoiceninja;

Creates a dedicated database for Invoice Ninja

CREATE USER 'invoiceninja'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD_HERE';

Creates a restricted database user

GRANT ALL PRIVILEGES ON invoiceninja.* TO 'invoiceninja'@'localhost';

Grants full access only to the Invoice Ninja database

FLUSH PRIVILEGES;
EXIT;

Terminal showing SQL database and user configuration commands.

Step 6: Install PHP 8.3 from Sury Repository

Debian 12 ships with older PHP versions, so we add the Sury PHP repository.

apt install ca-certificates apt-transport-https lsb-release curl gpg

Installs tools required to securely add external repositories

curl -fsSL https://packages.sury.org/php/apt.gpg | gpg --dearmor -o /usr/share/keyrings/php.gpg

Imports and verifies the PHP repository signing key

echo "deb [signed-by=/usr/share/keyrings/php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list

Registers the PHP repository

apt update

Reloads package metadata

Install PHP and required extensions

apt install php8.3 php8.3-cli php8.3-common php8.3-fpm php8.3-mysql php8.3-xml php8.3-curl php8.3-zip php8.3-mbstring php8.3-bcmath php8.3-gd php8.3-intl php8.3-opcache

These extensions are required for:

Database access
PDF generation
Internationalization
Performance optimization
Laravel framework compatibility

Enable Apache ↔ PHP-FPM integration:

a2enmod proxy_fcgi setenvif rewrite
a2enconf php8.3-fpm
systemctl restart apache2

Verify PHP:

php -v

Step 7: Download and Prepare Invoice Ninja

mkdir -p /var/www/html/invoiceninja
cd /var/www/html/invoiceninja

Creates the application directory

wget https://github.com/invoiceninja/invoiceninja/releases/latest/download/invoiceninja.tar

Downloads the latest Invoice Ninja release

Terminal showing file download commands and transfer output.

tar -xvzf invoiceninja.tar
rm invoiceninja.tar

Extracts and cleans up the archive

Set correct permissions

chown -R www-data:www-data /var/www/html/invoiceninja
chmod -R 755 /var/www/html/invoiceninja
chmod -R 775 storage bootstrap/cache

This ensures:

Apache can read the files
Laravel can write cache and logs

Terminal showing file ownership or permission commands.

Step 8: Configure Apache Virtual Host

nano /etc/apache2/sites-available/invoiceninja.conf

<VirtualHost *:80>
    ServerName invoices.example.com
    DocumentRoot /var/www/html/invoiceninja/public

    <Directory /var/www/html/invoiceninja/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Terminal showing web server configuration text.

Enable it:

a2ensite invoiceninja.conf
a2dissite 000-default.conf
apachectl configtest
systemctl reload apache2

Terminal showing an Apache configuration test.

Step 9: Configure Invoice Ninja Environment

cp .env.example .env
nano .env

APP_NAME=InvoiceNinja
APP_ENV=production
APP_DEBUG=false
APP_URL=http://invoices.example.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=invoiceninja
DB_USERNAME=invoiceninja
DB_PASSWORD=STRONG_PASSWORD_HERE

SESSION_DRIVER=file
CACHE_DRIVER=file
QUEUE_CONNECTION=sync

Terminal showing the GNU nano editor and configuration text.

Secure the file:

chown www-data:www-data .env

Step 10: Initialize Invoice Ninja

php artisan key:generate

Terminal showing php commands or output during Initialize Invoice Ninja.

Generates encryption keys

php artisan optimize:clear

Clears cached config/routes/views

php artisan migrate

Creates database tables

mkdir -p storage/framework/{sessions,cache,views}
chown -R www-data:www-data storage/framework
chmod -R 775 storage/framework
php artisan optimize:clear
systemctl restart apache2

Terminal showing file and directory setup commands.

Step 11: Configure Cron Jobs

crontab -e

Add:

* * * * * cd /var/www/html/invoiceninja && php artisan schedule:run >> /dev/null 2>&1

This enables:

Email sending
Invoice reminders
Recurring invoices
Background tasks

Step 12: Enable SSL (HTTPS)

apt install certbot python3-certbot-apache

certbot --apache -d debian-tutorials.shape.host

Replace with:

yourdomain.com

Certbot:

Issues a free SSL certificate
Updates Apache config
Enables auto-renewal

Open:

https://invoices.example.com

Complete the web installer and start invoicing

Application Settings and Database Configuration

On the Invoice Ninja Setup page, configure the core application settings.
Ensure the Application URL matches your domain and that HTTPS is enabled, which is strongly recommended for production deployments on Debian 12.
In the Database Connection section, enter your MySQL/MariaDB credentials, including host, port, database name, username, and password, then click Test connection to verify database access.

Invoice Ninja installation form with application and database settings.

Create the First Administrator Account

This step creates the first administrator account for your Invoice Ninja installation on Debian 12.
Provide the first name, last name, email address, and password for the admin user.
Accept the Terms of Service and Privacy Policy, then click Submit to complete the web-based installation.

Invoice Ninja initial administrator account form.

Invoice Ninja Login Page

After the installation process is completed, the Invoice Ninja login page is displayed.
Log in using the email address and password created during the setup.
If configured, Two-Factor Authentication (2FA) can be used for enhanced security.
Click Login to access the Invoice Ninja dashboard and start managing your invoices.

Dacă vrei, pot:

Welcome to Invoice Ninja – Initial Company Setup

After successfully installing Invoice Ninja on Debian 12 and logging in for the first time, the welcome dialog is displayed.
Here, define the Company Name, select the preferred Language, and choose the default Currency.
Click Save to store the settings and continue to the main dashboard.

Invoice Ninja company setup dialog over the dashboard.

Invoice Ninja Dashboard Overview

After completing the initial setup, you are redirected to the Invoice Ninja dashboard.
This dashboard provides an overview of your financial data, including recent transactions, payments, outstanding invoices, and activity summaries.
The left sidebar allows you to manage clients, products, invoices, recurring invoices, reports, and system settings.

Invoice Ninja dashboard with invoice statistics and financial charts.

You now have a fully explained, production-ready Invoice Ninja v5 installation on Debian 12 using modern PHP, secure database access, scheduled background jobs, and HTTPS.

For hosting financial and business-critical applications with full control and reliability, Shape.Host Cloud VPS provides an excellent foundation for self-hosted infrastructure.