HOWTO: Install Invoice Ninja v5 on Arch Linux

HOWTO: Install Invoice Ninja v5 on Arch Linux

Health Warning

This article is based on my experience using Arch on a VPS from OVH. This was a clean install of the VPS and Invoice Ninja was the first application to be installed so that there could be no conflicts with other packages or applications. Also there is no guarantee that the Arch ISO you or your VPS provider is using is the same as that of OVH so you might need to adapt the section below on Required Packages to suit your needs.

The Arch Linux ISO installation automatically creates a user in /etc/passwd called “http” for web servers with a home folder of /srv/http. This document assumes that

  1. the Invoice Ninja files are installed in the /srv/http/hosts/invoiceninja folder
  2. the web server is configured to run as the http user in the http group

You must change these in every command if your installation is different.

Needless to say that I am not responsible if anything breaks on your system. You use this guide at your own risk!

First Steps

Make sure that all the system packages are up to date:

sudo pacman -Syu

If one of the updated packages is a new Linux kernel, reboot the VPS.

Warnings from any Perl update about “Setting locale failed” can be ignored for now as Invoice Ninja is a PHP app, but I recommend that you fix them at some point.

Required Packages

As of Invoice Ninja v5.1.40, PHP 8 is supported.

The following packages need to be installed:

  • mariadb mariadb-libs

  • php php-fpm php-gd

  • cronie

  • composer

  • git

  • vi

  • ttf-roboto

      sudo pacman -S mariadb mariadb-libs php php-fpm php-gd cronie composer git vi ttf-roboto

If you intend to use SnapPDF to generate PDF files for your invoices (rather than the legacy PhantomJS), these additional packages are required:

  • at-spi2-atk

  • atk

  • gtk3

  • mesa

  • nss

      sudo pacman -S at-spi2-atk atk gtk3 mesa nss

You also need to install the web server of your choice.

Unfortunately the packages above will also install the latest version of PHP8 as a dependency which will have to be taken into consideration when configuring the web server (see the Prepare Web Server section below).

Install Invoice Ninja

  • Download the latest Invoice Ninja release from here

  • Unzip this release into /srv/http/hosts/invoiceninja

  • Change the file and folder ownership:

      sudo chown -R http:http /srv/http/hosts/invoiceninja

Prepare Cron (cronie)

sudo systemctl enable --now cronie

Prepare Database (MariaDB)

  • I highly recommend reading Arch’s excellent wiki on how to install MariaDB, create the initial database, setup systemd so that the database server starts automatically upon reboot, start the server and secure it.

  • Run

      sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
      sudo systemctl enable --now mysqld
      sudo mysql_secure_installation
  • Login to MariaDB

      sudo mysql -u root -p

    and enter the root password you entered while running mysql_secure_installation when asked

  • Create the Invoice Ninja user and database - you can/should change the schema, user and password in the code below to suit your needs, particularly the password (the “identified by” bit)

      CREATE SCHEMA `db-ninja-01` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
      CREATE USER 'ninja'@'localhost' IDENTIFIED BY 'ninja';
      GRANT ALL PRIVILEGES ON `db-ninja-01`.* TO 'ninja'@'localhost';

Prepare Invoice Ninja

There are a number of things that need to be changed in the PHP configuration

  • Edit /etc/php/php.ini file (edit these values to suit your requirements):

      file_uploads = On
      allow_url_fopen = On
      short_open_tag = On
      max_execution_time = 360
      memory_limit = 256M
      upload_max_filesize = 100M
      date.timezone = <your timezone> [optional]

    Then run

      sudo systemctl enable --now php-fpm
  • Setup PHP for Invoice Ninja

      cd /srv/http/hosts/invoiceninja
      sudo -u http /usr/bin/php /usr/bin/composer i --no-dev

    This will list any additional extensions that must be enabled in /etc/php/php.ini. Once done, restart the php-fpm service

      sudo systemctl restart php-fpm
  • Configure Invoice Ninja

      cd /srv/http/hosts/invoiceninja
    • Create .env file
      Copy the supplied .env.example file:

        sudo -u http cp .env.example .env

      Create a minimal .env file:

        sudo -u http printf "NINJA_ENVIRONMENT=selfhost\nAPP_NAME=\"Invoice Ninja\"\nAPP_ENV=production\nAPP_KEY=\nAPP_DEBUG=false\nAPP_URL=\nREQUIRE_HTTPS=\nDB_CONNECTION=db-ninja-01\nDB_DATABASE1=\nDB_USERNAME1=\nDB_PASSWORD1=\nPHANTOMJS_PDF_GENERATION=false\n" | sudo -u http tee .env
    • Edit .env file
      Now edit .env (as the http user) and change DB_DATABASE1, DB_USERNAME1 and DB_PASSWORD1 to match the values you entered when you created the database above. Also check that the value of PHANTOMJS_PDF_GENERATION is correct for your needs.

    • Setup the Invoice Ninja key and database:

        sudo -u http php artisan key:generate
        sudo -u http php artisan migrate:fresh --seed
    • Setup the Invoice Ninja cron job
      If you are comfortable using vi or know how override the default system editor run

        sudo crontab -u http -e

      and enter

        * * * * * php /srv/http/hosts/invoiceninja/artisan schedule:run >> /dev/null 2>&1

      Alternatively run these commands

        sudo printf "* * * * * php \"path_to_invoice_ninja_installation_folder\"/artisan schedule:run\n >> /dev/null 2>&1" | sudo tee /var/spool/cron/http
        sudo chmod 0600 /var/spool/cron/http
    • Check the SnapPDF Dependencies
      [If you have PHANTOMJS_PDF_GENERATION=true in .env you can ignore this section]

      Change the XXXXXX in the file path below to the actual number of the folder name on disk - it changes with each new Chrome version

        cd /srv/http/hosts/invoiceninja/vendor/beganovich/snappdf/versions/XXXXXX-Linux_x64/chrome-linux
        sudo -h http ldd chrome | grep not

      Install any that are missing (change “library_name” and “package_name” as appropriate):

        sudo pacman -Fy
        sudo pacman -F "library_name"
        sudo pacman -S "package_name"

Prepare Web Server

You need to configure your chosen web server to

  1. run as the http user and group
  2. load the php-fpm configuration files
  3. serve the Invoice Ninja files
  4. setup any SSL certificates
  5. create folders for the server log files

Again I refer you to the Arch wiki for your chosen web server for information on how to do this.

  • Apache
    In the section for your Invoice Ninja folder/directory add:

      <FilesMatch \.php$>
      	SetHandler "proxy:unix:/run/php-fpm/php-fpm.sock|fcgi://localhost"

    Enable and start Apache:

      sudo systemctl enable --now httpd
    In the section for your Invoice Ninja folder/directory, find the block beginning “location ~” and make sure it contains the fastcgi_* line in this example code:

      location ~ \.php$ {
      	# ADD THIS
      	fastcgi_pass unix:/run/php-fpm/php-fpm.sock;

    Enable and start NGINX:

      sudo systemctl enable --now nginx
  • Other web servers
    Follow the instructions for that server

Run Invoice Ninja

Load the Invoice Ninja site URL into your browser and answer the on-screen setup questions.

NOTE: If setup passes the “Test PDF” stage but you don’t see the actual PDF in another tab of your browser, the SnapPDF app is probably missing a library so revisit “SnapPDF Dependencies” above.

Finally backup and keep safe the Invoice Ninja .env file.

Congratulations - you’re done!

Post v4.5.x Migration [Optional]

If you are migrating from v4.5.x it is advisable to check that the data came across correctly:

	sudo -u http php /srv/http/hosts/invoiceninja/artisan ninja:check-data

Things to Remember

  • Whenever you make changes to .env you MUST run

      sudo -u http php /srv/http/hosts/invoiceninja/artisan optimize


  • Any time the Invoice Ninja ecosystem barfs run

      chown -R http:http /srv/http/hosts/invoiceninja

    This will cure a lot of issues that can crop up due to unexpected file permissions.

#### Revision History
Version Last Edited Remarks
1.5 2021-04-12 @ 09:02 UTC Update systemctl instructions
1.4 2021-04-11 @ 10:32 UTC Correct MySQL initialisation code
1.3 2021-04-08 @ 15:42 UTC Remove references to PHP7 now that Invoice Ninja supports PHP 8
1.2 2021-03-15 @ 09:24 UTC Change MySQL code to setup Invoice Ninja database to match code in app setup screen
1.1 2021-03-08 @ 20:26 UTC Add ttf-roboto to required packages (March 2021 version of OVH Arch ISO removed it from base packages)
1.0 2021-03-08 @ 12:34 UTC Initial Posting


This is awesome, thanks!!

Thanks @hillel - appreciate it. Arch is the best platform I’ve used IN (and other apps) on so it would be brilliant to get this linked into the main docs IMHO :wink:

100% agreed, it’s being worked on :slight_smile:

We plan to link to this guide from as well as in the main docs.

Thanks again for taking the time to write this up!

Awesome contribution


@TechnicallyComputers As are yours :+1:

1 Like

Wow! Well done!

I have it running in a Docker container but I prefer the “normal” way. I already installed it and it works so thank you very much!
Now I have to move the stuff from the docker container to that one. Why is “Import/Export” only import? :smiley:

You could add the update process as well. Or just via the gui?

Thanks again!

1 Like

Awesome, glad to hear it!

We plan to add an export feature (and many others…) with time, until then you can export your data as CSV in the reports.

Not sure I understand your second question? You can update via the UI or you can use the API.

Thanks for your kind words. Glad it worked for you :slight_smile:

I deliberately didn’t say anything about the update process as there are several ways to do it. Personally I use the update mechanism inside the IN app (ie gui)

Heyho @hillel and @brackenhill-mob

Where are the reports? I can’t find it … :confused: So my plan is to move from docker to this here =)

I wasn’t quite sure about the update process because I use the docker image with pull etc command. I thought there might be some permissions issues or something.

Anyhow, the guide is brilliant and thanks again. Especially the PDF way is really great! :wink:

There should be a reports options towards the bottom of the left menu bar.

Oh yeah. Too obvious. Sorry. But that way doesn’t really work. I used the database of the docker container.


You need to change ninja.* to db-ninja-01.* right?

@Dan Done. Good catch.

@ben Do you need to update the code in the app to reflect this? I missed this one when reporting the buglet first time around.

You could change all systemctl enable and systemctl start in just systemctl enable --now.

Not a big deal but quicker.

What is barfs?

Any time the Invoice Ninja ecosystem barfs run

Done. I started using systemd when it first came out and the --now switch didn’t work (lots of bug reports) so I never used it and forgot about it. Thanks for the nudge.

Google is your friend. A polite way to put it is “the act of being ill” :wink:

Nah, google is not my friend. I don’t use it. I still prefer to have a conversations :wink:
All good. I’m going to use another search engine :wink:

@brackenhill-mob code snippet looks just fine to me. What should be changed?

@ben You’re good. I pointed out the bug to you on Slack and forgot to upload my master markdown file here with the update/fix. I only realised after I’d made some more corrections. My bad.

1 Like