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

This tutorial will be showing you how to install InvoiceNinja on Ubuntu 20.04 with Apache or Nginx web server. InvoiceNinja is an open-source, self-hosted invoice software, a low-cost alternative to commercial online invoice platforms such as Freshbooks. InvoiceNinja provides hosted invoice service, but if you like to self host the software, you can follow the instructions below.

Install-InvoiceNinja-on-Ubuntu-20.04-Server

InvoiceNinja Features

  • With InvoiceNinja, you can send invoices to your clients by using your own domain name and brand.
  • Manage invoicing for multiple businesses all under one account.
  • Save time by automatically billing long-term clients with recurring invoices.
  • Easily create and send beautiful proposals to your customers.
  • Attach 3rd Party Files to Invoices.
  • Create Project Tasks & Track Time, so you can get rid of third-party time trackers like clockify.me.
  • Organize and plan your client’s work with a visual project management tool.
  • Allow your clients to see all their transactions with you in one glance.
  • Zapier automation allows you to transfer data between your invoicing account and popular apps including Gmail, Google Sheets, QuickBooks Online, Slack, Pipeline, MailChimp, and hundreds more.
  • Request deposits & partial payments using the same invoice again and again.
  • Use a pre-written auto-reminder email sequence to remind clients your invoice needs to be paid.
  • Receive notifications when a client views and pays your invoice.
  • And many more

Prerequisites

To follow this tutorial, you need an Ubuntu 20.04 OS running on a remote server. If you are looking for a virtual private server (VPS), I recommend Kamatera VPS, which features:

  • 30 days free trial.
  • Starts at $4/month (1GB RAM)
  • High-performance KVM-based VPS
  • 9 data centers around the world, including the United States, Canada, UK, Germany, The Netherlands, Hong Kong, and Isreal.

Follow the tutorial linked below to create your Linux VPS server at Kamatera.

InvoiceNinja requires PHP and MySQL/MariaDB. To follow this tutorial, you should have already set up a LAMP stack or LEMP stack. If you haven’t already done so, please use one of the following guides.

And you also need a domain name, so your clients can see the invoice via your domain name. I registered my domain name at NameCheap because the price is low and they give whois privacy protection free for life.

It’s very important that your server can send emails, so your clients can receive your invoice. Follow the tutorial linked below to set up SMTP relay on Ubuntu.

Now let’s install InvoiceNinja.

Step 1: Download InvoiceNinja Install Zip File on Ubuntu 20.04 Server

Login into your Ubuntu 20.04 server via SSH. Then run the following command to download the latest version of InvoiceNinja zip file onto your server.

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

Once downloaded, extract the archive to the /var/www/ directory with unzip.

sudo apt install unzip

sudo mkdir -p /var/www/invoiceninja/

sudo unzip invoiceninja.zip -d /var/www/invoiceninja/

The -d option specifies the target directory. InvoiceNinja web files will be extracted to /var/www/invoiceninja.

Then we need to change the owner of this directory to www-data so that the web server can write to this directory.

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

We also need to change the permission of the storage directory.

sudo chmod 755 /var/www/invoiceninja/storage/ -R

Step 2: Create a Database and User in MariaDB

Log into MariaDB database server with the following command.

sudo mysql

Then create a database for Invoice Ninja. This tutorial names the database invoiceninja. You can use whatever name you like.

create database invoiceninja;

Create the database user. Again, you can use your preferred name for this user. Replace your-password with your preferred password.

create user ninja@localhost identified by 'your-password';

Grant this user all privileges on the invoiceninja database.

grant all privileges on invoiceninja.* to ninja@localhost;

Flush privileges and exit.

flush privileges;

exit;

Step 3: Install PHP Modules

Ubuntu 20.04 ships with PHP7.4, but InvoiceNinja is already compatible with PHP8.0, so we install PHP8.0 for better performance. Run the following commands to install PHP modules required or recommended by InvoiceNinja.

sudo apt install software-properties-common

sudo add-apt-repository ppa:ondrej/php -y

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

Then restart Apache. (If you use Nginx, you don’t need to restart Nginx.)

sudo systemctl restart apache2

Step 4: Configure InvoiceNinja

Go to the InvoiceNinja web root.

cd /var/www/invoiceninja/

Copy the example .env file.

sudo cp .env.example .env

Edit this file with a command-line text editor like Nano.

sudo nano .env

Find the following line.

APP_URL=http://localhost

Change the URL to something like https://invoice.yourdomain.com, so you will be able to access InvoiceNinja using this sub-domain.

Then edit the database connection details. Enter the database name, database user, and password created in step 2.

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

Hint: If your password contains special characters, you can use double quotes like this: DB_PASSWORD="ninja_password".

Save and close the file. Change the owner to www-data.

sudo chown www-data:www-data /var/www/invoiceninja/.env

Next, run the following command to generate a unique app key for your InvoiceNinja installation.

sudo php8.0 /var/www/invoiceninja/artisan key:generate

And migrate the database.

sudo php8.0 /var/www/invoiceninja/artisan migrate:fresh --seed

Step 5: Setting Up Web Server

We can use Apache or Nginx web server.

Apache

If you prefer Apache, create a virtual host file for Invoice Ninja.

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

Put the following text into the file. Replace the red-colored text with your actual data. Don’t forget to set A record for the domain name. (Note that the web root is set to /var/www/invoice-ninja/public/, not /var/www/invoice-ninja/)

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

Save and close the file. Then enable this virtual host.

sudo a2ensite invoice-ninja.conf

We need to enable the rewrite module.

sudo a2enmod rewrite

Restart Apache for the changes to take effect.

sudo systemctl restart apache2

Now you can access the Invoice Ninja setup wizard page (invoice.yourdomain.com/setup). If you see the default Apache page instead of the setup wizard, then you need to disable the default virtual host.

sudo a2dissite 000-default.conf

And restart Apache.

Before entering any information in the setup wizard, we need to enable HTTPS.

Nginx

If you prefer Nginx, create a invoiceninja.conf file in /etc/nginx/conf.d/ directory.

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

Put the following text into the file. Replace the red-colored text with your actual data. Don’t forget to create DNS A record for this sub-domain. (Note that the web root is set to /var/www/invoiceninja/public/, not /var/www/invoiceninja/)

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= 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.0-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;
}

Save and close the file. Then test Nginx configuration.

sudo nginx -t

If the test is successful, reload Nginx for the changes to take effect.

sudo systemctl reload nginx

Now you can access the Invoice Ninja setup wizard page (invoice.yourdomain.com/setup). Before entering any information in the setup wizard, we need to enable HTTPS.

Step 6: Enabling HTTPS

To encrypt the HTTP traffic, we can enable HTTPS by installing a free TLS certificate issued from Let’s Encrypt. Run the following command to install Let’s Encrypt client (certbot) on Ubuntu 20.04 server.

sudo apt install certbot

If you use Nginx, then you also need to install the Certbot Nginx plugin.

sudo apt install python3-certbot-nginx

Next, run the following command to obtain and install TLS certificate.

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d invoice.yourdomain.com

If you use Apache, install the Certbot Apache plugin.

sudo apt install python3-certbot-apache

And run this command to obtain and install TLS certificate.

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d invoice.yourdomain.com

Where

  • --nginx: Use the nginx plugin.
  • --apache: Use the Apache plugin.
  • --agree-tos: Agree to terms of service.
  • --redirect: Force HTTPS by 301 redirect.
  • --hsts: Add the Strict-Transport-Security header to every HTTP response. Forcing browser to always use TLS for the domain. Defends against SSL/TLS Stripping.
  • --staple-ocsp: Enables OCSP Stapling. A valid OCSP response is stapled to the certificate that the server offers during TLS.

The certificate should now be obtained and automatically installed.

invoice ninja ubuntu 18.04

Step 7: Finish Installation with the Setup Wizard

Now go to invoice.yourdomain.com/setup to launch the web-based setup wizard. First, you need to designate an URL for your InvoiceNinja installation (https://invoice.yourdomain.com).

invoiceninja web-based setup wizard

 

Then click the Test PDF button. If it’s successful, you will then enter the database connection credentials.

invoiceninja mariadb database connection

Click the Test connection button.

Next, Enter SMTP settings to make sure it can end invoices to your clients via email. If you use the free Sendinblue SMTP relay service, then enter your Sendinblue credentials here.

invoiceninja SMTP settings

 

  • Driver: SMTP
  • Host: smtp-relay.sendinblue.com
  • Username: your sendinblue username
  • Password: your sendinblue password
  • Port: 587
  • Encryption: STARTTLS

Click the Send test email button to check if it’s working.

Finally, create an admin account.

invoiceninja admin account

After creating the admin user, you can log into InvoiceNinja.

Troubleshooting

If you encounter the 500 server error when using InvoiceNinja, please check the logs under /var/www/invocieninja/storage/logs/ directory. Most likely it’s a permission problem, which can be fixed with:

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

Set Up Cron Jobs

We need to set up Cron jobs to send recurring invoices and email reminders. Edit the www-data user’s crontab file.

sudo -u www-data crontab -e

Add the following lines at the end of this file.

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

Save and close the file. Run the following command to test if the Cron jobs will execute without errors.

sudo /usr/bin/php8.0 /var/www/invoiceninja/artisan schedule:run

How to Change SMTP Settings

If you need to change SMTP settings, you need to edit the .env file.

sudo nano /var/www/invoiceninja/.env

Edit the following parameters, which is suitable for SMTP servers that require authentication.

MAIL_MAILER="smtp"
MAIL_HOST="hostname_of_smtp_server"
MAIL_PORT="587"
MAIL_USERNAME="[email protected]"
MAIL_PASSWORD="your_password"
MAIL_ENCRYPTION="tls"
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="Invoice"

If InvoiceNinja is installed on your mail server or you have set up SMTP relay with Sendinblue, then you should use the following parameters.

MAIL_MAILER="sendmail"
MAIL_HOST=""
MAIL_PORT=""
MAIL_USERNAME=""
MAIL_PASSWORD=""
MAIL_ENCRYPTION="none"
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="Invoice"

Save and close the file. Then clear the cache.

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

If the cache is cleared, you will see the following messages in the command output.

Configuration cache cleared!
Configuration cached successfully!
Route cache cleared!
Routes cached successfully!
Files cached successfully!

Still Can’t Send Emails?

Are you using iRedMail? iRedMail doesn’t allow you to log in as one user and send emails as another user. If you don’t like this restriction, you can disable the sender_login_mismatch checks in Postfix.

How to Upgrade Invoice Ninja

When a new version of InvoiceNinja is out, follow these steps to upgrade.

First, back up the database.

sudo mysqldump -u root invoiceninja > invoiceninja.sql

Then back up the web files.

sudo tar -cpzvf invoiceninaja.tar.gz /var/www/invoiceninja/

Next, download the InvoiceNinja zip file from Github and replace the content in /var/www/invoice-ninja/, and install the dependencies.

cd /var/www/invoice-ninja/

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

sudo -u www-data composer install

Remove the .env file.

sudo rm /var/www/invoiceninja/.env

Next, go to https://invoice.yourdomain.com/setup to re-run the setup wizard. The database schema will be upgraded in the process.

Conclusion

I hope this tutorial helped you install Invoice Ninja on Ubuntu 20.04 server. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂

Rate this tutorial
[Total: 5 Average: 5]

17 Responses to “How to Install InvoiceNinja on Ubuntu 20.04 Server with Apache/Nginx

  • Frank Aguirre
    4 years ago

    I will try this software.

  • Please help with Instructions for Invoice Ninja, CentOS 8, Nginx instructions.
    Thanks

  • Hey, thanks for the guide. I have installed Invoiceninja following this guide before and it was successful.

    But on a new VPS (with PHP 7.4), I followed every step in this guide and when I finish the installation on landing page (“/setup”), after clicking Submit button it gives me the “Whoops looks like something went wrong”. The result of “/update” page shows the error “Trying to access array offset on value of type int”.

    I guess this error is related to PHP and Laravel versions. Do you have any suggestions about it?

  • Joshua Karanja
    4 years ago

    Hi,

    I got stuck when I opened the url in browser and got “Error: app is already configured, backup then delete the .env file to re-run the setup”

    Kindly assist,

    Best Regards,
    Joshua.

  • hi, how autorenew ssl ? thanks

  • Andrew Byrd
    3 years ago

    I got this message at the end. Any ideas?

    Error: app is already configured, backup then delete the .env file to re-run the setup

    • I got this too. Go to your install directory and enter ‘sudo rm .env’
      .env should get created first run, but seemed like it was in the download.

      • After deleting .env file.. it gets me to the setup page but right submitting… It gives me a Error 500 page.
        If I restart or re-enter the my server address it gets me back to the page with: “Error: app is already configured, backup then delete the .env file to re-run the setup”

        Of course, I can delete the file and gets me to the setup page, but again back to the same error “Error 500” once my settings are entered.

        PLEASE HELP??

  • Please help with install of Invoice Ninja version 5 on Ubuntu 20.04. I can’t get these instructions to work on version 5.

    Thank you!

  • Сonfirm! There is an error in the .env file and deleting it does not help.

  • Gettings this error:
    Composer detected issues in your platform: Your Composer dependencies require a PHP version “>= 7.4.0”. You are running 7.3.33-1+ubuntu20.04.1+deb.sury.org+1.

    what should i do?

    • Xiao Guoan (Admin)
      2 years ago

      Hi Jonny,

      InvoiceNinja is now compatible with PHP7.4. You can install PHP7.4 with:

      sudo apt install php-imagick php7.4-fpm php7.4-mysql php7.4-common php7.4-gd php7.4-json php7.4-curl php7.4-zip php7.4-xml php7.4-mbstring php7.4-bz2 php7.4-intl php7.4-gmp
      

      Then set PHP7.4 as default.

      sudo update-alternatives --config php
  • After deleting .env file.. it gets me to the setup page but right submitting… It gives me a Error 500 page.
    If I restart or re-enter the my server address it gets me back to the page with: “Error: app is already configured, backup then delete the .env file to re-run the setup”

    Of course, I can delete the file and gets me to the setup page, but again back to the same error “Error 500” once my settings are entered.

    PLEASE HELP??

    • Xiao Guoan (Admin)
      2 years ago

      If you encounter the 500 server error when using InvoiceNinja, please check the logs under /var/www/invocieninja/storage/logs/ directory. Most likely it’s a permission problem, which can be fixed with:

      sudo chown www-data:www-data /var/www/invoice-ninja/storage/framework/cache/data/ -R
  • Hello,

    Having an issue with the Crontab command… Copied below from the terminal.
    Any chance anyone can help?? Using the 5.4 version of Invoice Ninja but everything same with the above setup info from LinuxBabe.

    admin@p1invoiceninjasrv1:~$ sudo /usr/bin/php7.4 /var/www/invoice-ninja/artisan ninja:send-invoices

    Command “ninja:send-invoices” is not defined.

    Did you mean one of these?
    ninja:backup-update
    ninja:check-data
    ninja:check-db
    ninja:create-account
    ninja:create-single-account
    ninja:create-test-data
    ninja:demo-mode
    ninja:design-update
    ninja:import
    ninja:mobile-localization
    ninja:old-import
    ninja:pcheck-data
    ninja:post-update
    ninja:react
    ninja:s3-cleanup
    ninja:send-recurring
    ninja:send-reminders
    ninja:send-test-emails
    ninja:subdomain
    ninja:sync-users
    ninja:translations
    ninja:type-check

    • Xiao Guoan (Admin)
      2 years ago

      Hi, I just updated this tutorial for the latest 5.4 version. The correct Cron jobs are as follows:

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

      You can install PHP8.0 with:

      sudo add-apt-repository ppa:ondrej/php -y
      
      sudo apt install php-imagick php8.0 php8.0-mysql php8.0-fpm php8.0-common php8.0-bcmath php8.0-gd php8.0-curl php8.0-zip php8.0-xml php8.0-mbstring php8.0-bz2 php8.0-intl php8.0-gmp
      
  • Raaj Menon
    1 year ago

    hi there,
    I went through step by step, really nice tutorial and got to the last step for setup and I get this message:

    Oops, something does not look right!
    Make sure all requirements are satisfied. Abd all these extensions have already been loaded. Please see screenshot: https://d.pr/i/WOoY07

    Any help would be appreciated

Leave a Comment

  • Comments with links are moderated by admin before published.
  • Your email address will not be published.
  • Use <pre> ... </pre> HTML tag to quote the output from your terminal/console.
  • Please use the community (https://community.linuxbabe.com) for questions unrelated to this article.
  • I don't have time to answer every question. Making a donation would incentivize me to spend more time answering questions.

The maximum upload file size: 2 MB. You can upload: image. Links to YouTube, Facebook, Twitter and other services inserted in the comment text will be automatically embedded. Drop file here