Note: use this guide for Ubuntu 20.04
Install Invoice Ninja v5.5 on Ubuntu 22.04
Ubuntu and debian based distros are highly reccomended for running the InvoiceNinja software. If you are on a red hat based distro, or other OS, it would probably be best to just use a container and host the docker image.
First: Install dependencies
Invoice Ninja is built on PHP 8.1, so we must first install that, and the recommended extensions for it. We can also install MariaDB for SQL service, NGINX will be used for webhosting in my tutorial, and vim as tools for later steps.
$ sudo apt update $ sudo apt dist-upgrade -y $ sudo apt install php8.1-bcmath php8.1-gmp php8.1-fileinfo \ php8.1-gd php8.1-mbstring php8.1-pdo php8.1-xml php8.1-cli \ php8.1-curl php8.1-zip php8.1-gmp php8.1-mysql php8.1-fpm $ sudo apt install mariadb-server mariadb-client nginx vim
Second: Configure MariaDB
Start, and enable services for mariadb, the program/service that manages your SQL database and the incoming and outgoing communication it has with other applications like Invoice Ninja.
$ sudo systemctl enable --now mariadb
This command will take you through a guided wizard to initialize the SQL database. Remember Make sure to change your SQL root password, and save that password somewhere safe and secure, to protect access to the databases.
$ mysql_secure_installation Enter current password for root (enter for none): Switch to unix_socket authentication [Y/n] n Change the root password [Y/n] y Remove anonymous users? [Y/n] y Disallow root login remotely? [Y/n] y Remove test database and access to it? [Y/n] y Reload privilege tables now? [Y/n] y
These commands will directly access the SQL database through the services provided by mariadb. We will create a database with any arbitrary name ‘ninjadb’ in this example, and create arbitrary username and password combination ‘ninja’ and ‘ninjapass’. The database name will be used by InvoiceNinja during the server setup after installation is complete, as well as the username and password you specify here, in order for InvoiceNinja to login to the SQL database with read/write permission.
$ mysql -u root -p Enter Password: ****** MariaDB .. > create database invoicedb; MariaDB .. > create user 'ninja'@'localhost' identified by 'ninjapass'; MariaDB .. > grant all privileges on invoicedb.* to 'ninja'@'localhost'; MariaDB .. > flush privileges; MariaDB .. > exit
Third: Configure NGINX
FOR TESTING - NOT for Production use - OpenSSL certification
You should not need to do this. I am about to show you NGINX configuration file that points to an example based openssl cert. Most of you would be using letsencrypt, or some other CA. I am not going to provide a guide to setup letsencrypt. So for the purposes of this guide, the NGINX configuration will use an instant OpenSSL certificate that is not particularly trusted on the Internet.
$ sudo mkdir -p /etc/nginx/cert $ sudo openssl req -new -x509 -days 365 -nodes -out /etc/nginx/cert/ninja.crt -keyout /etc/nginx/cert/ninja.key
The default NGINX install on Ubuntu has a pesky default website located at /etc/nginx/sites-enabled/default - and for our cases, we do not want this default website hosted by nginx. When left unconfigured, this page presents some security loopholes. It can also cause conflicts sometimes. Lets remove it.
$ sudo rm /etc/nginx/sites-enabled/default
NGINX configuration page for website
Create a text file with the ‘.conf’ ending in the /etc/nginx/conf.d/ directory, and any code in it will be included and run with the settings under /etc/nginx/nginx.conf.
$ sudo vim /etc/nginx/conf.d/invoiceninja.conf
Press ‘i’ to enter insert mode, and paste this server configuration.
Review it line by line, and edit the server name, root path, ssl path, php-fpm socket path, etc, as necessary.
You cannot copy paste this entire document, you will need to edit appropriate sections to accomodate your own environment. I will try to “”“indicate”“” when specific strings of text need your attention.
NOTE this guide uses a standard self-signed cert for SSL, so in the NGINX config sample file below, you will need to edit the lines for the path of an example of a self-signed cert, to instead point at your own real certs.
Make sure you change any variables for your environment, “”“recommended by use of quotations”“”.
Verify your NGINX configuration with the following command, and troubleshoot any errors on the lines it specifies for you;
$ nginx -t
For Ubuntu Server edition, you might have apache2 installed and enabled by defualt. Follow the steps below to disable apache2, and enable nginx instead for webhosting service.
Disable & stop Apache2. Start & enable NGINX.
$ sudo systemctl stop apache2 $ sudo systemctl disable apache2 $ sudo systemctl enable nginx $ sudo systemctl start nginx
Fourth: Installing Invoice Ninja
Installing the application files in the NGINX web server directory.
Please visit https://github.com/invoiceninja/invoiceninja/releases to get the latest github release of InvoiceNinja from the team. Look closely at what you are downloading, the list also includes recent updates to v4. Dropping to root will help us navigate the folder structure without permission issues.
$ sudo bash # cd /usr/share/nginx # mkdir invoiceninja && cd invoiceninja # wget <latest invoiceninja.zip url link> # unzip invoiceninja.zip # rm invoiceninja.zip
The Invoice Ninja package doesn’t contain a
.env file, so it won’t overwrite your existing file when you update. It does include a
.env.example file. Note, that the
.env file will automatically be populated with
# cp .env.example .env
# cp .env /path/to/backup/.env.bak
Prepare Invoice Ninja permissions
Set permissions for the directory and all its contents to allow web server permission to view and edit files. The default user for Ubuntu and debian based distros is
# chown -R www-data:www-data /usr/share/nginx/invoiceninja
Enable Cron job automation
Now, there is need to enable cron job that will run some sort of regular maintenance, or you get a nasty red exclamation mark error in InvoiceNinja after logging in. See here for more: Redirecting...
$ sudo -u www-data crontab -e
Then copy paste the following into the bottom of your cron file, which will be run for something to do with laravel which InvoiceNinja depends on.
This will run, as user www-data, with the explicitly correct php version, the artisan schedule command in order to provide Invoice Ninja application with the backend services it needs to work properly. Edit the path according to your environment, also, specifying which version of php to use in the crontab, and other places, ensures we don’t inadvertently use the wrong version on a system with multiple versions of php running.
* * * * * php8.1 /usr/share/nginx/"""invoiceninja"""/artisan schedule:run >> /dev/null 2>&1
BACKUP FILES & DATA
- Backup the
.envfile which holds primary server configurations
- Backup the SQL database, by dumping it into a file.
- Backup the contents of the
public/storagedirectory, where logo images, PDFs, attachments, etc are all saved in a nested structure, and referenced by the SQL database so the program can find them later.