HOWTO: Install Invoice Ninja v5 on Arch Linux

brackenhill-mob · March 8, 2021, 12:34pm

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

the Invoice Ninja files are installed in the /srv/http/hosts/invoiceninja folder
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';
  FLUSH PRIVILEGES;
  EXIT;

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]
  extension=bcmath
  extension=gd
  extension=iconv
  extension=mysqli
  extension=pdo_mysql

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
Either
Copy the supplied .env.example file:

  sudo -u http cp .env.example .env

Or
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

run as the http user and group
load the php-fpm configuration files
serve the Invoice Ninja files
setup any SSL certificates
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"
  </FilesMatch>

Enable and start Apache:

  sudo systemctl enable --now httpd

NGINX
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

AND THEN BACK IT UP!!

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

hillel · March 8, 2021, 1:06pm

hillel · March 8, 2021, 1:06pm

Hi,

This is awesome, thanks!!

brackenhill-mob · March 8, 2021, 2:32pm

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

hillel · March 8, 2021, 2:37pm

100% agreed, it’s being worked on

We plan to link to this guide from https://www.invoiceninja.org as well as in the main docs.

Thanks again for taking the time to write this up!

TechnicallyComputers · March 18, 2021, 2:48am

Awesome contribution

brackenhill-mob · March 18, 2021, 7:05am

@TechnicallyComputers As are yours

Dan · March 21, 2021, 6:28pm

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?

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

Thanks again!

hillel · March 21, 2021, 6:57pm

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.

brackenhill-mob · March 22, 2021, 10:04am

Thanks for your kind words. Glad it worked for you

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)

Dan · March 24, 2021, 7:01am

Heyho @hillel and @brackenhill-mob

Where are the reports? I can’t find it … 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!

hillel · March 24, 2021, 9:39am

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

Dan · March 28, 2021, 3:15am

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

Dan · April 11, 2021, 2:50am

Hey

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

brackenhill-mob · April 11, 2021, 10:34am

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

Dan · April 11, 2021, 8:49pm

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

Not a big deal but quicker.

Edit:
What is barfs?

Any time the Invoice Ninja ecosystem barfs run

brackenhill-mob · April 12, 2021, 9:07am

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”

Dan · April 12, 2021, 9:31am

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

ben · April 12, 2021, 11:30am

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

brackenhill-mob · April 12, 2021, 12:03pm

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