Invoice Ninja is a popular open-source platform for managing invoices, clients, and payments. However, due to their frequent release cycle, installation can sometimes be challenging.

This guide provides a step-by-step working method to install Invoice Ninja on a self-hosted Debian 12 Bookworm system. Before you start, ensure you have MariaDB, NGINX, and PHP 8.2 installed and configured.

Step 1: Install Required PHP Modules

Invoice Ninja requires several PHP modules to function correctly. Run the following command to install them:

sudo apt install php8.2-bcmath php8.2-gd php8.2-mbstring php8.2-xml php8.2-curl php8.2-zip php8.2-mysql php8.2-fpm php8.2-imagick php8.2-soap php8.2-common php8.2-intl php8.2-iconv php8.2-openssl

Step 2: Create the Installation Directory

Create a directory for Invoice Ninja under /var/app:

sudo mkdir -p /var/app/invoiceninja
cd /var/app/invoiceninja

Step 3: Download Invoice Ninja

Download the latest release of Invoice Ninja from their official GitHub repository. At the time of writing, version v5.9.6 is the latest stable version:

wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.9.6/invoiceninja.tar

Step 4: Extract the Files

Extract the downloaded .tar file:

sudo tar -xf invoiceninja.tar

Once extracted, delete the compressed file to save space:

sudo rm -rf invoiceninja.tar

Step 5: Set Proper Ownership

Change the ownership of the invoiceninja directory and its contents to the www-data user:

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

Step 6: Install Composer Dependencies

If Composer is not installed, you can install it with:

sudo apt install composer

Then, install the required dependencies for Invoice Ninja:

sudo -u www-data composer install

Step 7: Configure the Environment File

Copy the default .env file and make necessary updates for your environment:

sudo cp .env.example .env

Change the ownership of the .env file to www-data:

sudo chown www-data: .env

Edit the .env file to match your database and system configuration. Ensure you update the following values:

APP_URL=https://yourdomain.com
DB_DATABASE=invoiceninja
DB_USERNAME=invoiceninja_user
DB_PASSWORD=yourpassword

Step 8: Generate the Application Key

Generate a secure application key:

sudo -u www-data php artisan key:generate

Step 9: Clear Config Cache

Clear any cached configurations:

php artisan config:clear

Step 10: Change Log Folder Permission

Make sure the storage and cache folder is accessible by the application

sudo chown -R www-data: /var/app/invoiceninja/storage 
sudo chown -R www-data: /var/app/invoiceninja/bootstrap/cache

sudo chmod -R 775 /var/app/invoiceninja/storage 
sudo chmod -R 775 /var/app/invoiceninja/bootstrap/cache

Step 10: Setup Con Job to Run Schedule

Setup cron job to run schedule.

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

Step 11: Setup NGINX config with Cloudflare SSL

server {
            server_name www.example example.com;
            return       301 https://example.com$request_uri;
        }

server {

  add_header X-Content-Type-Options nosniff;
  add_header X-Frame-Options: SAMEORIGIN;

  #listen 80;
  server_name example.com www.example.com;

  listen 443 ssl http2;
  listen [::]:443 ssl http2;

        ssl_certificate         /var/app/ssl/example.com.pem.crt;
        ssl_certificate_key     /var/app/ssl/example.com.private.key;

  root /var/app/invoiceninja/public;

  index index.php index.html
  access_log /var/app/log/example.com.access.log;
  error_log  /var/app/log/example.com.error.log;


   location / {

	try_files $uri $uri/ /index.php?$args;
    }

    location ~ .php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

Final Steps

At this point, Invoice Ninja is installed and ready to configure in your browser. Ensure your NGINX configuration points to the /var/app/invoiceninja/public directory as the root. Restart PHP-FPM and NGINX to apply changes:

sudo systemctl restart php8.2-fpm
sudo systemctl restart nginx

Troubleshooting

If you encounter any issues, ensure all dependencies are installed and check the NGINX and PHP-FPM logs for errors:

sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/php8.2-fpm.log

With this guide, you should have a fully functional Invoice Ninja setup on your Debian 12 Bookworm server. Enjoy managing your invoices efficiently!