Managing invoices, tracking expenses, and processing payments are critical tasks for any business or freelancer. Invoice Ninja offers a powerful, self-hosted solution that puts you in complete control of your billing operations. This open-source invoicing platform supports over 40 payment gateways, provides comprehensive financial tracking, and eliminates recurring subscription fees associated with cloud-based alternatives.

This comprehensive guide walks you through installing Invoice Ninja on Debian 13 (Trixie). You’ll learn how to set up the complete LEMP stack infrastructure, configure the database environment, and deploy a production-ready invoicing system. Whether you’re a small business owner seeking independence from third-party services or a system administrator deploying billing solutions for clients, this tutorial provides detailed instructions to get Invoice Ninja running on your Debian server.

By the end of this guide, you’ll have a fully functional invoicing system capable of generating professional invoices, accepting online payments, tracking time and expenses, and managing client relationships—all hosted on your own infrastructure.

Prerequisites and System Requirements

Before beginning the installation process, ensure your environment meets the necessary specifications for running Invoice Ninja smoothly.

Server Requirements

Your Debian 13 server should have at least 2GB of RAM for optimal performance, particularly when handling multiple concurrent users or processing large databases. A minimum of 1GB free disk space is required, though allocating additional storage is recommended for long-term invoice archival and attachment storage. You’ll need root or sudo privileges to install packages and configure services. A stable internet connection is essential for downloading dependencies and accessing package repositories.

Software Stack Requirements

Invoice Ninja runs on the LEMP stack, which consists of Linux (Debian 13), Nginx web server, MySQL or MariaDB database, and PHP. Specifically, you’ll need PHP 8.1 or 8.2 with several extensions: php-curl, php-gd, php-intl, php-json, php-mbstring, php-mysql, php-xml, php-zip, php-bcmath, php-soap, and php-gmp. These extensions enable Invoice Ninja’s image processing, internationalization, JSON handling, and mathematical calculations. Composer, the PHP dependency manager, is required for installing Invoice Ninja’s Laravel framework dependencies. While optional, an SSL certificate and domain name are strongly recommended for production environments to ensure secure data transmission.

Step 1: Update Debian 13 System

System updates ensure compatibility with the latest security patches and package versions. Begin by updating your package repository index to retrieve information about the newest versions of packages and their dependencies:

sudo apt update

Next, upgrade all installed packages to their latest versions:

sudo apt upgrade -y

The -y flag automatically confirms the upgrade process. If kernel updates are installed, reboot your server to apply changes:

sudo reboot

After rebooting, verify your Debian version:

lsb_release -a

Regular system maintenance prevents compatibility issues and protects against known vulnerabilities. This foundation ensures smooth installation of Invoice Ninja and its dependencies.

Step 2: Install Nginx Web Server

Nginx serves as the high-performance web server that delivers Invoice Ninja’s web interface to users. Its event-driven architecture efficiently handles numerous concurrent connections while consuming minimal resources.

Install Nginx using the APT package manager:

sudo apt install nginx -y

Start the Nginx service and enable it to launch automatically on system boot:

sudo systemctl start nginx
sudo systemctl enable nginx

Verify that Nginx is running correctly:

sudo systemctl status nginx

You should see an “active (running)” status. If you’re using UFW firewall, allow HTTP and HTTPS traffic:

sudo ufw allow 'Nginx Full'

Test your Nginx installation by navigating to your server’s IP address in a web browser. You should see the default Nginx welcome page. This confirms the web server is operational and ready to host Invoice Ninja.

Step 3: Install and Configure MariaDB Database

Invoice Ninja stores all application data—including invoices, clients, payments, and user accounts—in a relational database. MariaDB provides a robust, MySQL-compatible database management system ideal for this purpose.

Install MariaDB server and client packages:

sudo apt install mariadb-server mariadb-client -y

Start and enable the MariaDB service:

sudo systemctl start mariadb
sudo systemctl enable mariadb

Secure your MariaDB installation by running the security script:

sudo mysql_secure_installation

The script prompts several security-related questions. Set a strong root password when prompted. Answer “Y” to remove anonymous users, disallow remote root login, remove the test database, and reload privilege tables. These steps harden your database against unauthorized access.

Now create a dedicated database and user for Invoice Ninja. Log into the MySQL console:

sudo mysql -u root -p

Enter your root password. Execute the following SQL commands:

CREATE DATABASE invoiceninjadb;
CREATE USER 'invoiceninja'@'localhost' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON invoiceninjadb.* TO 'invoiceninja'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace your_strong_password with a secure password containing uppercase letters, lowercase letters, numbers, and special characters. This dedicated user follows the principle of least privilege, granting only necessary database access to Invoice Ninja.

Step 4: Install PHP 8.2 and Required Extensions

Invoice Ninja is built on the Laravel PHP framework, requiring PHP 8.2 and numerous extensions for full functionality. PHP-FPM (FastCGI Process Manager) provides efficient PHP processing for Nginx.

Install PHP-FPM and the PHP CLI:

sudo apt install php8.2-fpm php8.2-cli -y

Install all required PHP extensions in a single command:

sudo apt install php8.2-curl php8.2-gd php8.2-intl php8.2-mbstring php8.2-mysql php8.2-xml php8.2-zip php8.2-bcmath php8.2-soap php8.2-gmp php8.2-common -y

Each extension serves specific functions: php-curl handles HTTP requests to payment gateways, php-gd processes images for logos and avatars, php-intl provides internationalization support, php-mbstring manages multibyte string operations, php-mysql enables database connectivity, php-xml processes XML data, php-zip handles compressed files, php-bcmath performs arbitrary precision mathematics for financial calculations, php-soap integrates with SOAP-based services, and php-gmp provides GNU multiple precision arithmetic.

Verify your PHP installation:

php -v

You should see PHP 8.2.x information displayed. Check installed modules:

php -m

Start and enable PHP-FPM:

sudo systemctl start php8.2-fpm
sudo systemctl enable php8.2-fpm

Confirm PHP-FPM is running:

sudo systemctl status php8.2-fpm

PHP-FPM’s process isolation and performance optimizations make it ideal for production PHP applications like Invoice Ninja.

Step 5: Install Composer

Composer manages PHP dependencies for Laravel applications. Invoice Ninja requires Composer to install its numerous framework and library dependencies.

Download the Composer installer:

curl -sS https://getcomposer.org/installer -o composer-setup.php

Install Composer globally so it’s accessible system-wide:

sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Remove the installer script:

rm composer-setup.php

Verify Composer installation:

composer --version

You should see the Composer version number. Global installation allows you to run Composer from any directory, simplifying dependency management during installation and future updates.

Step 6: Download and Extract Invoice Ninja

Navigate to the web root directory where Invoice Ninja will reside:

cd /var/www/html

You have two methods for downloading Invoice Ninja. The first method automatically retrieves the latest stable release:

VER=$(curl -s https://api.github.com/repos/invoiceninja/invoiceninja/releases/latest|grep tag_name|cut -d '"' -f 4|sed 's/v//')
sudo wget https://github.com/invoiceninja/invoiceninja/releases/download/v${VER}/invoiceninja.tar.gz

This uses the GitHub API to identify and download the most recent version. Alternatively, download a specific version if you require a particular release:

sudo wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.12.34/invoiceninja.tar.gz

Create a directory for Invoice Ninja:

sudo mkdir /var/www/html/invoiceninja

Extract the downloaded archive:

sudo tar -xzf invoiceninja.tar.gz -C /var/www/html/invoiceninja

Remove the archive file to free disk space:

sudo rm invoiceninja.tar.gz

Verify extraction by listing the directory contents:

ls -la /var/www/html/invoiceninja

You should see Invoice Ninja’s directory structure, including folders like app, bootstrap, config, database, public, resources, routes, and storage. Always review release notes for version-specific requirements or breaking changes before installing specific versions.

Step 7: Set Proper Permissions and Ownership

Correct file permissions and ownership ensure Invoice Ninja operates securely while maintaining necessary write access to specific directories. Nginx runs as the www-data user, so Invoice Ninja files must be owned by this user.

Change ownership of the entire Invoice Ninja directory:

sudo chown -R www-data:www-data /var/www/html/invoiceninja

Set directory permissions to 755 (owner can read, write, execute; others can read and execute):

sudo find /var/www/html/invoiceninja -type d -exec chmod 755 {} \;

Set file permissions to 644 (owner can read and write; others can read only):

sudo find /var/www/html/invoiceninja -type f -exec chmod 644 {} \;

The storage directory requires elevated permissions for writing logs, cache files, and uploaded documents:

sudo chmod -R 775 /var/www/html/invoiceninja/storage

Similarly, the bootstrap cache directory needs write permissions:

sudo chmod -R 775 /var/www/html/invoiceninja/bootstrap/cache

These permission settings follow security best practices: restrictive default permissions with targeted write access only where necessary. This prevents unauthorized file modifications while allowing Invoice Ninja to function properly.

Step 8: Configure Environment File

The environment file contains sensitive configuration data including database credentials, application settings, and API keys. Laravel applications use .env files to store environment-specific configurations.

Navigate to the Invoice Ninja directory:

cd /var/www/html/invoiceninja

Copy the example environment file:

sudo cp .env.example .env

Change ownership to www-data:

sudo chown www-data:www-data .env

Edit the environment file:

sudo nano .env

Configure these essential settings:

APP_URL=http://your-domain.com
DB_HOST=localhost
DB_DATABASE=invoiceninjadb
DB_USERNAME=invoiceninja
DB_PASSWORD=your_strong_password
APP_DEBUG=false

Replace your-domain.com with your actual domain or server IP address. Update your_strong_password with the database password you created earlier. Setting APP_DEBUG=false disables debug mode for production environments, preventing sensitive error information from being displayed to users.

You can also configure mail settings for email functionality:

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls

Save and exit the editor by pressing Ctrl+X, then Y, then Enter. Never commit the .env file to version control or expose it publicly, as it contains sensitive credentials. Additional configuration options include queue settings, cache drivers, and session handlers for advanced deployments.

Step 9: Install Composer Dependencies

Composer installs all PHP packages and dependencies required by Invoice Ninja’s Laravel framework. This process downloads and configures dozens of libraries that power Invoice Ninja’s functionality.

Navigate to the Invoice Ninja directory if not already there:

cd /var/www/html/invoiceninja

Run Composer as the www-data user:

sudo -u www-data composer install --no-dev -o

The --no-dev flag excludes development dependencies, reducing installation size and improving performance. The -o flag optimizes the autoloader for production use. This process may take several minutes depending on your server’s internet speed and processing power.

If you encounter memory limit errors during installation, temporarily increase PHP’s memory limit by editing /etc/php/8.2/cli/php.ini and setting memory_limit = 512M or higher. Wait for the installation to complete without errors. You’ll see output indicating which packages are being installed and their versions.

Step 10: Generate Application Key and Optimize

Laravel requires a unique application key for encrypting session data, cookies, and other sensitive information. Generate this key using Laravel’s Artisan command-line tool:

sudo -u www-data php artisan key:generate

This creates a random 32-character string and adds it to your .env file. Run database migrations to create Invoice Ninja’s database schema:

sudo -u www-data php artisan migrate:fresh --seed

This command creates all necessary database tables and seeds initial data. Optimize the application for production performance:

sudo -u www-data php artisan optimize

Clear configuration cache to ensure environment changes are recognized:

sudo -u www-data php artisan config:clear

Clear compiled view templates:

sudo -u www-data php artisan view:clear

Running artisan commands as www-data ensures generated files have correct ownership. Laravel’s Artisan CLI provides powerful tools for managing Laravel applications, including database operations, cache management, and task scheduling.

Step 11: Configure Nginx Virtual Host

Nginx requires a virtual host configuration to serve Invoice Ninja. This configuration defines how Nginx processes requests for your Invoice Ninja installation.

Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/invoiceninja.conf

Add the following configuration:

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/html/invoiceninja/public;
    index index.php index.html;
    
    client_max_body_size 20M;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.ht {
        deny all;
    }
    
    location ~ /\.env {
        deny all;
    }
}

Replace your-domain.com with your actual domain. Key directives include: server_name defines the domain, root points to Invoice Ninja’s public directory (Laravel’s entry point), client_max_body_size allows file uploads up to 20MB, the location block handles PHP processing through PHP-FPM, and security directives deny access to hidden files and the .env file.

Create a symbolic link to enable the site:

sudo ln -s /etc/nginx/sites-available/invoiceninja.conf /etc/nginx/sites-enabled/

Test the Nginx configuration for syntax errors:

sudo nginx -t

If the test succeeds, reload Nginx to apply changes:

sudo systemctl reload nginx

For production environments, configure SSL using Let’s Encrypt certificates. Install Certbot, obtain a certificate, and update your Nginx configuration to redirect HTTP to HTTPS.

Step 12: Configure Cron Job for Scheduled Tasks

Invoice Ninja relies on Laravel’s task scheduler for automated operations including sending recurring invoices, payment reminders, and email notifications. A cron job triggers the scheduler every minute.

Edit the crontab for the www-data user:

sudo crontab -u www-data -e

If prompted to select an editor, choose nano or your preferred text editor. Add this line at the end:

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

The five asterisks represent minute, hour, day of month, month, and day of week—all set to * means “every minute.” This command navigates to Invoice Ninja’s directory, runs the Laravel scheduler, and redirects output to /dev/null to prevent mail notifications.

Save and exit the crontab editor. Verify the cron job was added:

sudo crontab -u www-data -l

Without this cron job, recurring invoices won’t be sent automatically, and scheduled tasks won’t execute. The Laravel scheduler internally determines which tasks should run at any given time based on your Invoice Ninja configuration.

Step 13: Complete Web-Based Installation

With server configuration complete, finish the installation through Invoice Ninja’s web interface. Open your web browser and navigate to your Invoice Ninja URL:

http://your-domain.com

Or use your server’s IP address if you haven’t configured a domain. The installation wizard guides you through final setup steps.

The first screen displays Invoice Ninja’s terms of service and privacy policy. Review these documents and click Accept to continue. The database setup screen appears next, displaying pre-filled credentials from your .env file. Click “Test Connection” to verify database connectivity. If the test fails, return to your .env file and verify database credentials match those created earlier.

Create your admin account by entering an email address (this becomes your username) and a strong password. Confirm your password in the second field. This account has full administrative privileges, so use a unique, secure password.

Enter your company information including business name, preferred currency, language, country, and timezone. These settings configure how invoices display and calculate amounts. You can modify these later in the settings panel.

Click “Submit” or “Complete Installation” to finalize setup. Invoice Ninja processes your configuration, creates necessary database entries, and redirects you to the login page. Sign in using the admin credentials you just created.

Upon first login, you’ll see the Invoice Ninja dashboard displaying key metrics, recent invoices, and quick action buttons. Take time to explore the interface and familiarize yourself with features like client management, invoice creation, payment gateways, and reports.

Post-Installation Configuration and Security

Several post-installation tasks optimize security and functionality for production use.

Configure Payment Gateways

Navigate to Settings > Payment Settings to enable payment processors. Invoice Ninja supports Stripe, PayPal, Authorize.net, Braintree, and over 40 other gateways. Select your preferred gateway, enter API credentials from your payment processor account, and configure settings like accepted payment methods. Test the integration by processing a small test transaction before going live.

Email Configuration

Reliable email delivery ensures clients receive invoices and payment receipts. If you didn’t configure mail settings in the .env file, access Settings > Email Settings. Enter your SMTP server details including host, port, username, password, and encryption method (TLS or SSL). Test email functionality by sending a test message.

Security Hardening

Install an SSL certificate to encrypt data transmission. Let’s Encrypt provides free certificates. Install Certbot, run sudo certbot --nginx, and follow prompts to obtain and install certificates. Certbot automatically updates your Nginx configuration for HTTPS.

Update your .env file to use the HTTPS URL:

APP_URL=https://your-domain.com

Clear the configuration cache:

sudo -u www-data php artisan config:clear

Ensure APP_DEBUG=false in production environments. Enable debugging only when troubleshooting issues, and disable it immediately afterward.

Configure UFW firewall rules to restrict access:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Implement regular database and file backups. Use automated backup solutions or cron jobs to schedule daily backups stored offsite.

Performance Optimization

Enable PHP OPcache to cache compiled PHP bytecode, reducing execution time. Edit /etc/php/8.2/fpm/php.ini and verify OPcache is enabled:

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000

Restart PHP-FPM after changes:

sudo systemctl restart php8.2-fpm

Adjust PHP memory limits if handling large invoices or many attachments. Increase memory_limit in php.ini from the default 128M to 256M or higher based on your needs.

Common Troubleshooting Tips

Even with careful configuration, issues occasionally arise. These troubleshooting techniques resolve common problems.

500 Internal Server Error

This generic error indicates server-side issues. Check PHP-FPM status:

sudo systemctl status php8.2-fpm

If stopped, start the service. Review Nginx error logs for specific error messages:

sudo tail -f /var/log/nginx/error.log

Check Laravel application logs:

tail -f /var/www/html/invoiceninja/storage/logs/laravel.log

Common causes include PHP syntax errors, missing extensions, or permission issues. The log files provide detailed error information to guide resolution.

Database Connection Issues

If Invoice Ninja can’t connect to the database, verify credentials in your .env file match the database user and password created earlier. Test database connectivity manually:

mysql -u invoiceninja -p invoiceninjadb

Enter the database password. Successful login confirms credentials are correct. Check that MariaDB is running:

sudo systemctl status mariadb

Permission Errors

Permission errors appear when www-data lacks necessary file access. Reapply ownership recursively:

sudo chown -R www-data:www-data /var/www/html/invoiceninja

Ensure storage directories have write permissions:

sudo chmod -R 775 /var/www/html/invoiceninja/storage
sudo chmod -R 775 /var/www/html/invoiceninja/bootstrap/cache

White Screen or Blank Page

A white screen typically indicates PHP errors. Enable debug mode temporarily by setting APP_DEBUG=true in .env, then reload the page to see error details. Clear all caches:

sudo -u www-data php artisan cache:clear
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan view:clear

Check PHP error logs at /var/log/php8.2-fpm.log for additional information.

File Upload Issues

If file uploads fail, increase Nginx’s client body size. Edit your Nginx virtual host configuration and increase client_max_body_size from 20M to a higher value. Similarly, adjust PHP upload limits in /etc/php/8.2/fpm/php.ini:

upload_max_filesize = 50M
post_max_size = 50M

Restart Nginx and PHP-FPM after configuration changes.

Maintenance and Updates

Regular maintenance ensures Invoice Ninja remains secure, stable, and feature-rich.

Update Process

Before updating, backup your database and application files. Export the database:

mysqldump -u invoiceninja -p invoiceninjadb > invoiceninja_backup.sql

Backup application files:

sudo tar -czf invoiceninja_files_backup.tar.gz /var/www/html/invoiceninja

Download the latest Invoice Ninja version from GitHub. Extract files to a temporary directory, then carefully copy updated files to your installation directory while preserving your .env file and storage directory. Run Composer to update dependencies:

sudo -u www-data composer install --no-dev -o

Execute database migrations:

sudo -u www-data php artisan migrate

Clear caches:

sudo -u www-data php artisan cache:clear
sudo -u www-data php artisan config:clear

Test thoroughly after updates before serving production traffic.

Ongoing Maintenance

Schedule automated backups daily using cron jobs. Store backups on separate servers or cloud storage for disaster recovery. Monitor application logs regularly for errors or unusual activity. Keep Debian system packages updated with apt update && apt upgrade. Review Invoice Ninja’s changelog before updating to identify breaking changes or new requirements. Join the Invoice Ninja community forums and GitHub repository to stay informed about security advisories and best practices.

Congratulations! You have successfully installed InvoiceNinja. Thanks for using this tutorial for installing Invoice Ninja free invoice generator on your Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Invoice Ninja website.