Why is this guide here?
I had a hell of a time getting InvoiceNinja self-hosted on a server… each guide that I found was missing some dependency or something else and I just couldn’t get to the blessed “setup” page… so I started doing it myself…
Instructions
This guide will take you from a clean/fresh installation of Ubuntu 24.X to the setup menu for self-hosted InvoiceNinja using a localhost SQL server. The location of Ubuntu does not matter but it is a lot easier if you are hosting it in a virtual environment where you can take quick snapshots, just in case. It doesn’t matter if you’re hosting Ubuntu or you’re hosting on someone else’s computer (cloud).
Requirements:
- Ubuntu 24.X live server with a sudo user account and terminal access
- A static IP address for the server. You can configure it during Ubuntu installation or reserve a DHCP address.
- Access to WAN
Recommendations:
- Putty (or similar) ← this is a recommendation that will save you time and hassle
- A static IPv4 WAN address or a DDNS pointer. This is especially helpful if you’re going to make this public facing. If you’re hosting it in the cloud you will probably get a static public IPv4 address.
Step 1 - Getting Ubuntu Ready
If you haven’t stood up a server you will want to download the Ubuntu 24.X live server .iso here and create a new server. I recommend doing this as a virtual guest as virtualization gives a LOT of extra benefits. If you don’t and choose to install on a bare metal machine this guide will still be the same.
Important: Select Install OpenSSH server during initial configuration. You will want to be able to use Putty, or similar, to access the server, especially if your console viewer does not have the ability to paste from clipboard!
Once you have installed the operating system log in using the credentials you used during installation and start copying the below code and pasting it into your terminal. (recommend using Putty)
You should be able to copy straight from this guide into your Putty terminal by right-clicking on the screen. Be careful to watch where the cursor is because it will paste where that is, not where your mouse is.
Step 2 - Install InvoiceNinja it’s required dependancies
sudo su --enter your password–
apt update && apt upgrade -y
apt install apache2 -y
systemctl stop apache2.service
systemctl start apache2.service
systemctl enable apache2.service
apt install mariadb-server mariadb-client -y --you can use another sql db if you wish–
systemctl stop mariadb.service
systemctl start mariadb.service
systemctl enable mariadb.service
mysql_secure_installation
–Selections are in italics–
Enter current password for root (enter for none): press enter here
Switch to unix_socket authentication [Y/n] n
Change the root password [Y/n] y
This is where you will enter your root password for your new SQL server… this can, and should, be different from your sudo user account.
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
reboot now --this will get everything updated and any new kernels loaded and ready to move on–
sudo su --enter your password–
apt install software-properties-common -y
add-apt-repository ppa:ondrej/php -y
add-apt-repository ppa:ondrej/apache2 -y
apt update
apt install php8.4 -y --you can load the other dependencies if you wish but I found that it’s better to be able to see exactly which dependencies are still needed–
nano /etc/php/8.4/apache2/php.ini
Here you will want to search for and update specific entries.
You can update anything but these are recommended::
file_uploads = On
allow_url_fopen = On
short_open_tag = On
memory_limit = 256M
upload_max_filesize = 100M
max_execution_time = 360
systemctl restart apache2.service
mysql -u root -p --enter the sqldb root password you selected above, not your sudo password–
–Inside the sql prompt you will enter the following–
create database invoiceninja;
CREATE USER ‘invoiceninja’@’localhost’ IDENTIFIED BY 'password'; --you will want to enter your own password after IDENTIFIED BY–
GRANT ALL ON invoiceninja.* TO 'invoiceninja'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION; --use the same password as you did when you created the user–
FLUSH PRIVILEGES;
EXIT; --this will exit the sql prompt–
mkdir /var/www/html/invoiceninja && cd /var/www/html/invoiceninja
wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.12.6/invoiceninja.tar --this will grab version 5.12.6 which has a minimum php version of 8.2–
tar -xvzf invoiceninja.tar --unzip time!–
rm invoiceninja.tar --no need to keep the tar file–
chown -R www-data:www-data /var/www/html/invoiceninja/
chmod -R 755 /var/www/html/invoiceninja/
nano /etc/apache2/sites-available/invoiceninja.conf
to SSL or not to SSL
Here’s where you’re going to have to make a decision… and I suggest you use HTTPS over HTTP. For the ServerName field this is where you will select your FQDN for your NinjaInvoice server. Make sure you update it!
You will need to have the certificate files already in the path to have the HTTPS config work. I suggest using a publicly trusted certificate (I get mine from namecheap) so that your end user doesn’t have to accept/trust the cert. You will need to have: (1) the certificate and (2) the private key in RSA. The following assumes that you have loaded those two files into /etc/ssl and you can add another directory level if desired such as /etc/ssl/company or whatever… just make sure that you update the virtual host conf.
If you’re going to use SSL you need to enable it:
a2enmod ssl
Copy and paste the entire virtual host config for HTTP only::
<VirtualHost *:80>
DocumentRoot /var/www/html/invoiceninja/public
ServerName sub.domain.com
<Directory /var/www/html/invoiceninja/public>
Options +FollowSymlinks
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
Copy and paste the entire virtual host config for HTTP+S::
Note: You will start with HTTP & HTTPS and then come back after config to enforce HTTPS with a redirect
<VirtualHost *:80>
DocumentRoot /var/www/html/invoiceninja/public
ServerName sub.domain.com
<Directory /var/www/html/invoiceninja/public>
Options +FollowSymlinks
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
#Redirect permanent / https://sub.domain.com
</VirtualHost>
<VirtualHost *:443>
DocumentRoot /var/www/html/invoiceninja/public
ServerName sub.domain.com
SSLEngine on
SSLCertificateFile /etc/ssl/cert.pem
SSLCertificateKeyFile /etc/ssl/key.pem
SSLCertificateChainFile /etc/ssl/cert.pem
<Directory /var/www/html/invoiceninja/public>
Options +FollowSymlinks
AllowOverride All
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
a2ensite invoiceninja.conf
a2enmod rewrite
apachectl configtest --this does a syntax check for you for OK–
Note: If configtest is not OK then you need to fix that before you can successfully restart the apache2 service and continue the installation. If your problem is your certificate it will work once and then fail once it tries to actually use it.
systemctl restart apache2.service
Stop for a break here and check to make sure your certificate is working properly
At this stage you want to test your certificate before enforcing it. From another machine make sure that the server is listening on TCP port 443. If your certificate is not loaded properly it will likely work once and then fail. You want it to keep showing that it is listening on 443 no matter how many times you check.
You should also attempt to open the HTTPS address to force SSL certificate verification. If the certificate fails Apache2.service will stop and not start again. You need to ensure that your certificate is properly loaded before you continue on from here if you are going to use HTTPS, and especially if you are going to require HTTPS and reject HTTP.
After you’ve verified that your certificate is properly loaded (if applicable) continue:
cd /var/www/html/invoiceninja && cp .env.example .env
nano .env --here you need to update the following (at least) items–
APP_URL="https://sub.domain.com"
DB_DATABASE="invoiceninja"
DB_USERNAME="invoiceninja"
DB_PASSWORD="password"
Note: While the setup page still requires you to enter the information again and doesn’t copy from .env if you remove the entry, say DB_PASSWORD, it will throw you back to the setup page for some reason. I have not tested to see if you can just re-add the credentials in setup but if you readd the DB_PASSWORD it will allow you to go back to the dashboard.
hostnamectl set-hostname sub.domain.com --sets the hostname for the machine if not domain joined–
nano /etc/hosts --add your data here using format IPv4_address sub.domain.com sub–
apt install php8.4-fpm -y
chown www-data:www-data /var/www/html/invoiceninja/.env
apt install software-properties-common apt-transport-https ca-certificates gnupg2 -y
a2enmod mpm_event proxy_fcgi setenvif
a2enmod rewrite
a2dissite 000-default.conf --this will disable the default page–
systemctl restart apache2
Note: Here you will want to test your setup by going to http://sub.domain.com or the IPv4 address of the server. It will tell you what php modules you don’t have installed that it’s looking for. It won’t tell you it’s looking for -mysql… but you need it… so make sure you get it installed too. The following php modules should cover what you need but update as required/desired.
apt install php8.4-gd php8.4-curl php8.4-zip php8.4-mbstring php8.4-xml php8.4-bcmath php8.4-mysql -y
cd /var/www/html/invoiceninja && /usr/bin/php -d register_argc_argv=On artisan schedule:run >> /dev/null 2>&1
apt update && apt upgrade -y --final update check–
reboot now --this puts everything is place and has the server go through a final check before it’s time to set up and use your InvoiceNinja instance.–
Congratulations!!! You should now be able to access the setup page!
Here you will now want to enter your desired settings, specifically if you want to use HTTPS and enforce/require it or not. You should enter the SQL user credentials created earlier and test. Once you have a successful test you’re ready to set up your first account and start using InvoiceNinja.
If you’re using HTTPS!
After you’re all set up and verified that HTTPS works as desired you can go back into the virtual host and remove the # from #Redirect permanent / https://sub.domain.com. This will set a permanent redirect to HTTPS, even if your end users try for port 80.
After updating the virtual host configuration you’ll just need to reload Apache2.
systemctl reload apache2.service
That’s it!
You should now have InvoiceNinja v5 fully running on Ubuntu 24 (with HTTPS if configured). I hope this helps you all. I know I wish I had this a few nights ago.