How to Install InvoiceNinja on Ubuntu 22.04 Server with Apache/Nginx

Last Updated: December 10th, 2022

This tutorial will be showing you how to install InvoiceNinja on Ubuntu 22.04 with an Apache or Nginx web server. InvoiceNinja is an open-source, self-hosted invoice software and a low-cost alternative to commercial online invoice platforms such as Freshbooks. If you prefer to self-host your invoicing infrastructure, you can follow the instructions below.

InvoiceNinja Features

• Send customized invoices to your clients utilizing your own domain name and branding vectors.
• Manage billing and invoicing matrix arrays for multiple independent businesses under a single master administrator account.
• Automate billing schedules for long-term clients with native recurring invoice generators.
• Design and dispatch visually comprehensive project proposals directly to prospects.
• Track time windows and tasks dynamically, replacing standard resource tracking utilities like clockify.me.
• Leverage Zapier hooks to automate data migration workflows between InvoiceNinja and apps like Gmail, Slack, and QuickBooks.

Requirements

• An Ubuntu 22.04 LTS operating system running on a remote server with at least 1GB of RAM.
• A pre-configured web platform stack. InvoiceNinja is written in PHP and relies on MySQL/MariaDB database states.
• A domain name mapped correctly via your control registrar (e.g., NameCheap).
• A dependable SMTP relay layout (e.g., Postfix tied to an external transactional service) so system email actions do not get rejected.

Step 1: Download InvoiceNinja Web Files

Log in to your Ubuntu 22.04 server via SSH. Download the specific application production asset release structure directly onto your storage array:

wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.5.48/invoiceninja.zip

Once the download completes, extract the package into your web service pool and assign correct security permissions:

sudo apt install unzip
sudo mkdir -p /var/www/invoiceninja/
sudo unzip invoiceninja.zip -d /var/www/invoiceninja/
sudo chown www-data:www-data /var/www/invoiceninja/ -R

Step 2: Create a Database and User in MariaDB

Log into your database server environment:

sudo mysql

Provision an isolated database and map an authentic system user with strong credentials:

create database invoiceninja;
create user ninja@localhost identified by 'ninja_password';
grant all privileges on invoiceninja.* to ninja@localhost;
flush privileges;
exit;

Step 3: Install Required PHP Modules

Ubuntu 22.04 maps standard PHP8.1 tracking trees natively. Install the extensions required or recommended by InvoiceNinja:

sudo apt install php-imagick php8.1 php8.1-mysql php8.1-fpm php8.1-common php8.1-bcmath php8.1-gd php8.1-curl php8.1-zip php8.1-xml php8.1-mbstring php8.1-bz2 php8.1-intl php8.1-gmp

If you are utilizing an Apache stack environment, reload the handler module state:

sudo systemctl restart apache2

Step 4: Configure InvoiceNinja Environmental Variables

Navigate to your active web root and replicate the prototype configuration file template:

cd /var/www/invoiceninja/
sudo cp .env.example .env
sudo nano .env

Locate the target values and adjust them to map to your canonical URL path and database parameters:

APP_URL=https://invoice.yourdomain.com

DB_HOST=localhost
DB_DATABASE=invoiceninja
DB_USERNAME=ninja
DB_PASSWORD=ninja_password
DB_PORT=3306

Save changes and close the editor. Grant file privileges to the web process and populate your database state schemas using the artisan wrapper tools:

sudo chown www-data:www-data /var/www/invoiceninja/.env
sudo php8.1 /var/www/invoiceninja/artisan key:generate
sudo php8.1 /var/www/invoiceninja/artisan migrate:fresh --seed

Step 5: Setting Up Web Server Virtual Hosts

You can choose to serve InvoiceNinja using either Apache or Nginx. Note: The document root must point to the /public subdirectory.

Option A: Apache Setup

Create a dedicated configuration definition file:

sudo nano /etc/apache2/sites-available/invoice-ninja.conf

Add the following virtual host declaration block:

<VirtualHost *:80>
    ServerName invoice.yourdomain.com
    DocumentRoot /var/www/invoiceninja/public

    <Directory /var/www/invoiceninja/public>
       DirectoryIndex index.php
       Options +FollowSymLinks
       AllowOverride All
       Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/invoice-ninja.error.log
    CustomLog ${APACHE_LOG_DIR}/invoice-ninja.access.log combined
</VirtualHost>

Enable the site configuration site map, inject the core rewrite module engine, and reload the service:

sudo a2ensite invoice-ninja.conf
sudo a2enmod rewrite
sudo a2dissite 000-default.conf
sudo systemctl restart apache2

Option B: Nginx Setup

Create a dedicated config mapping block inside your definition directory:

sudo nano /etc/nginx/conf.d/invoiceninja.conf

Populate your routing values with the tracking syntax below:

server {
    listen   80;
    listen   [::]:80;
    server_name invoice.yourdomain.com;

    root /var/www/invoiceninja/public/;
    index index.php index.html index.htm;
    charset utf-8;
    client_max_body_size 20M;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    if (!-e $request_filename) {
       rewrite ^(.+)$ /index.php?q=$1 last;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    access_log  /var/log/nginx/invoiceninja.access.log;
    error_log   /var/log/nginx/invoiceninja.error.log;

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_intercept_errors off;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
    }

    location ~ /\.ht {
        deny all;
    }

    sendfile off;
}

Test the web engine parameters for runtime formatting consistency and apply changes:

sudo nginx -t
sudo systemctl reload nginx

Step 6: Enabling HTTPS Encryption Layers

Secure your traffic using the Certbot utility tool. Install the core program asset:

sudo apt install certbot

Execute the specific certificate automation sequence matching your chosen web environment setup:

# For Nginx Configurations
sudo apt install python3-certbot-nginx
sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d invoice.yourdomain.com

# For Apache Configurations
sudo apt install python3-certbot-apache
sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d invoice.yourdomain.com

Step 7: Finish Installation via the Web Interface Wizard

Navigate to https://invoice.yourdomain.com/setup in your web browser. Follow the setup wizard to verify the system's requirements, test PDF rendering engines, map database users, and configure your SMTP transactional credentials (e.g., using your custom platform parameters or external services like Sendinblue/Brevo).

Maintenance and Advanced Configurations

Automated Process Scheduling (Cron Jobs)

InvoiceNinja relies on persistent scheduling states to safely handle billing increments and recurring automated client actions. Open the crontab definition layer mapped directly under your web master system daemon identity:

sudo -u www-data crontab -e

Append the task blocks below directly to the file profile:

0 8 * * * /usr/bin/php8.1 /var/www/invoiceninja/artisan ninja:send-recurring > /dev/null
0 8 * * * /usr/bin/php8.1 /var/www/invoiceninja/artisan ninja:send-reminders > /dev/null
* * * * * /usr/bin/php8.1 /var/www/invoiceninja/artisan schedule:run >> /dev/null 2>&1

Modifying SMTP Parameters and Cache Optimizations

When adjustments to mail flow pipelines are necessary, modify environmental elements directly within your main production parameter file:

sudo nano /var/www/invoiceninja/.env

Once edits are applied to the mail parameters block, clear the internal application optimization cache layers to force the service to load updated metrics:

sudo -u www-data /usr/bin/php8.1 /var/www/invoiceninja/artisan optimize

Troubleshooting App Failures

If you encounter runtime issues or 500 error faults, evaluate the application logs located under /var/www/invoiceninja/storage/logs/. Most common faults originate from permission locks, which can be safely resolved by reapplying proper directory tracking flags:

sudo chown www-data:www-data /var/www/invoiceninja/.env
sudo chown www-data:www-data /var/www/invoiceninja/storage/framework/cache/data/ -R

How to Safely Upgrade InvoiceNinja

When updates are available, secure your historical configuration integrity before pulling structural application files:

# Backup operations
sudo mysqldump -u root invoiceninja > invoiceninja.sql
sudo tar -cpzvf invoiceninja.tar.gz /var/www/invoiceninja/

Once backup files are compiled safely out of your working paths, download and replace directory code branches, resolve dependencies using composer paths, delete the residual environment mapping flags, and access the web dashboard installer wizard tool to process schema state alterations smoothly.