Set Up Self Hosted InvoiceNinja to Keep Your Finances Organized, Your Data Safe, and Your Wallet Happy
A detailed technical guide on setting up a self hosted version of InvoiceNinja V5 of how to set up on an Ubuntu 22.04 VPS.
If you're like us, when you first started your business you might have decided to handle all of your accounting and invoicing by hand. It worked out great at first and kept things simple and straightforward as you began navigating the complexities of business ownership for the first time. But as your business grew, the task of manually entering details and tracking payments quickly became unwieldly and impractical.
This is where InvoiceNinja comes in. InvoiceNinja is an open source software that you can use to help keep yourself and your finances organized. There are two ways to get started: hosted and self hosted. The hosted option is a great way to get up and running fast, but at the cost of a recurring annual subscription. While on the other hand, the self hosted option is more complicated to set up, it will save you money in the long run and keep you in full control of your data (something we think a lot about these days). This tutorial will focus on the self hosted version.
One thing to note is if you want to remove the InvoiceNinja branding from the client facing portions, you'll need to buy a $30 annual white label license, which to me feels like fair compensation for a great product that's ultimately offered to the world for free.
Pros:
- Intuitive interface (very easy to learn)
- Saves time on repetitive tasks (no more looking for addresses or product/service costs)
- Detailed Tracking (at a glance see who owes what when)
- Incredibly customizable (invoices, user portal, etc)
- Automations (such as sending recurring invoices)
- Integrates with payment gateways (allowing for clients to pay directly by card etc)
- No limits that other packages have (as many clients, account users, branded client portal, etc.)
- You're in control (prices can't go up, services can't go out of business, accounts can't be closed)
- You own your data (accounts can't be closed and data can't be sold)
- Free forever (open source is always great)
Cons:
- Initial setup is a bit complex (hopefully this guide will help with this one)
- Customization can be technical and time consuming (though for most uses this might not be strictly necessary as there's so much great right out of the box)
Disclaimer: links in this article are affiliate links. Think of them like a small tip jar that helps keep the lights on during the creation of content like this.
Prerequisites
1. An Ubuntu 22.04 VPS like the inexpensive ones at Digital Ocean.
2. Basic knowledge of bash commands.
1. Set Up Your VPS
If you already have a VPS set up for other projects, this step can be largely skipped. The great part about this setup is that we can run multiple apps and services from the same VPS to maximize the resources we're already paying for.
If you're starting fresh and not sure how to get things configured, head over here to our other article and follow the steps through step 2, Setting Up Ubuntu for Production.
2. Set Up Your DNS
Now to get things kicked off in this tutorial, let's point our domain (or more likely, subdomain) over to our VPS. Head over to wherever you manage your domain's dns (likely with your domain registrar or your VPS host). If you still need a domain I think NameCheap is a great easy to use and affordable option.
I like to host InvoiceNinja on a subdomain as it makes accessing it straightforward and provides a nice look for the client portal. It's also much simpler than setting it up on a sub directory. To do so, we'll just need to add one record to point our subdomain over to our VPS ip address.
Type Hostname Value
A invoices.your-domain.com <your-VPS-ip>
3. Make Backups
This is really important anytime we're going to make big changes to a VPS. Accidents happen, and this will keep you out of your dark place when some random setting makes your server start to smoke.
4. Install php 8.3 and Extensions
It's important that we install the proper versions here otherwise it's likely our server will throw a lot of errors once it's up and running. Let's start with our php installation.
sudo add-apt-repository ppa:ondrej/php
sudo apt update
And now we'll install the extensions that the app will need to run.
sudo apt install php8.3-bcmath php8.3-gmp php8.3-fileinfo \
php8.3-gd php8.3-mbstring php8.3-pdo php8.3-xml php8.3-cli \
php8.3-curl php8.3-zip php8.3-gmp php8.3-mysql php8.3-fpm
5. Install mariaDB and Create Our Database
First things first we'll need to install our database server and client and enable it to start on startup.
sudo apt update
sudo apt install mariadb-server mariadb-client
sudo systemctl enable mariadb
It's also a good idea to secure our database a bit so we'll run a quick post install script. As you go through the wizard take the defaults for everything and skip setting a password.
sudo mysql_secure_installation
Once that's finished installing, we'll enter the mySQL prompt so we can interact with the database.
mysql
Once in the shell, we'll enter a few commands to build our database and set up our user and privileges.
CREATE DATABASE invoiceninja;
Don't forget to swap in your password here when setting up the user and save it because we'll be using it later.
CREATE USER 'ninja'@'localhost' IDENTIFIED BY <your_super_secure_password>;
We'll grant some privileges now.
GRANT ALL PRIVILEGES ON invoiceninja.* TO 'ninja'@'localhost';
And make sure they're applied.
FLUSH PRIVILEGES;
And when we're all done, we'll exit the shell again.
EXIT;
6. Install InvoiceNinja
Now we're at the point where we can actually install the app. As of writing this article the latest version is v5.11.62. If you want the latest version head over to InvoiceNinja's official self hosting site here and copy the link address from the download button. You can also find out more info from their official GitHub repo here. Just make sure you install the proper versions of php and it's extensions, as well as adjust the upcoming steps of the guide anywhere php is used.
wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.11.62/invoiceninja.tar
Create the directory that will be the app's new home.
sudo mkdir -p /var/www/invoiceninja/
Unpack the tar file we just downloaded.
sudo tar -xvf invoiceninja.tar -C /var/www/invoiceninja/
Update the ownership so the default Nginx user, www-data, will have the access it needs.
sudo chown www-data:www-data /var/www/invoiceninja/ -R
The storage directory also needs a little love.
sudo chmod 755 /var/www/invoiceninja/storage/ -R
7. Configure InvoiceNinja
Now we'll enter all of our details and get our new installation of Invoice Ninja ready to go.
First things first we'll fill out our .env file with all of the details our app will need to run properly. We'll use the .env.example as a good starter template.
sudo nano /var/www/invoiceninja/.env.example
When the file opens up, there's two basic changes we need to make. The first is to add our domain.
APP_URL=https://your.domain.com
The second is to enter all of our database details. Make sure these details match exactly what you used in the previous database step. If your password contains special symbols, you might have to wrap it in double quotes.
DB_DATABASE=invoiceninja
DB_USERNAME=ninja
DB_PASSWORD="your_super_secure_password"
The rest of the file should be good to go so we can save and close with and hit "ctrl + x", "y", and "enter" to save and exit. Now let's rename the file to .env so that our app will use the newly added settings.
sudo mv /var/www/invoiceninja/.env.example /var/www/invoiceninja/.env
Finally to keep our app nice and secure we'll generate a secure key.
sudo php8.3 /var/www/invoiceninja/artisan key:generate
8. Install and Configuring Nginx
We'll be using Nginx as our webserver to route the appropriate traffic over to InvoiceNinja. First, if you're not already, ssh into your VPS and begin the installation. Again, if you already have a server configured on your VPS, you can skip to the end of this step, and just add the config file along with any others you may have.
sudo apt update
sudo apt install nginx
Now it's time to start the server and enable it to start on startup.
sudo systemctl start nginx
sudo systemctl enable nginx
Now that our web server is up and running it's time to configure. First navigate to the
largely taken from the official docs
sudo nano /etc/nginx/conf.d/invoiceninja.conf
When the editor opens paste the following config (largely taken from the official docs), and hit "ctrl + x", "y", and "enter" to save and exit.
server {
listen 80;
server_name your.domain.here;
root /var/www/invoiceninja/public;
index index.php index.html index.htm;
client_max_body_size 20M;
gzip on;
gzip_types application/javascript application/x-javascript text/javascript text/plain application/xml application/json;
gzip_proxied no-cache no-store private expired auth;
gzip_min_length 1000;
# Allow access to index.php
location = /index.php {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
# Block all other .php requests
location ~ \.php$ {
return 403;
}
location / {
try_files $uri $uri/ /index.php?$query_string;
# Add your rewrite rule for non-existent files
if (!-e $request_filename) {
rewrite ^(.+)$ /index.php?q=$1 last;
}
}
location ~ /\.ht {
deny all;
}
}
Now we'll reload Nginx for the changes to take affect
sudo systemctl reload nginx
If you have other apps installed and running using Nginx already, you may run into an issue regarding the server_names_hash_bucket_size.conf already existing. If that's the case you can usually delete the file and simply allow the process to recreate it.
sudo rm /etc/nginx/conf.d/server_names_hash_bucket_size.conf
9. Set Up SSL
Making sure we're secure is the last thing we'll do on the webserver side before we hop over to our new web app to finish configurations. As usual we'll be using our wonderful certbot to take care of all the legwork and renewals.
sudo apt install certbot
sudo apt install python3-certbot-nginx
Now we'll run the certbot, the flags are just here to help us skip through some of the prompts more quickly and ensure we get all of the settings we want. Enter your email and your domain (no need to include https:// or www).
sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email your@email.com -d invoices.yourdomain.com
Once the script finishes running, hopefully we'll see a nice success message.
10. Setup the Web Portal
Now our server should be up and purring and our web portal should be ready for us to log in and setup. In your browser go to your.domain.com/setup and fill out the form and perform the tests. Make sure to use all of the same database info we used during set up and you should be good to go.
11. Set Up Cron Jobs
This step will allow InvoiceNinja to perform tasks such as sending recurring invoices. Let's open up our chrontab.
sudo -u www-data crontab -e
And paste these lines at the bottom.
#InvoiceNinja
* * * * * /usr/bin/php8.3 /var/www/invoiceninja/artisan schedule:run >> /dev/null>
Now and hit "ctrl + x", "y", and "enter" to save and exit.
12. Setup Email Capabilities
One of the great things about InvoiceNinja is it's ability to automatically send emails, but to get this functionality we'll need to do some additional configuration. SMTP servers are notoriously tricky to set up and ensure your emails will reach inboxes instead of spam folders, that's why I highly recommend you use a third party service to handle this part. One example is Brevo who has a very generous free tier. You can see their guide here on how to set up your domain to send emails through their servers.
Once you have your Brevo set up, head back over to your new InvoiceNinja web portal and go to Settings -> Email Settings and enter in your information.
At the end of the setup if you're still having issues with delivery I recommend checking out Mail Tester and MX Toolbox to help troubleshoot and figure out what's going wrong.
13. Updating
InvoiceNinja is actively being improved and developed, so you're sure to see some updates from time to time. Unless there's a large version upgrade, getting the latest version should be as easy as using the admin panel from your browser. If an update is available, you'll see a small exclamation mark in the bottom left corner of the panel, just click that and begin the update.
On your first attempt, you may have to explicitly grant ownership of the logs folder to Nginx, so if you're having trouble, this command should allow things to run smoothly in the future.
sudo chown -R www-data:www-data /var/www/invoiceninja/storage/logs
14. Troubleshooting
If you run into issues along the way there's a few places to look to figure out what's going on. The first is to check out the various error logs to see if you can find something interesting. There are two main places to look. Use "cd", "ls -a" to navigate the logs.
To open up and inspect a log I like to use a command like this to show you only the most recent lines (as some logs can be VERY long).
sudo tail -n 20 log.file
The first place to look is the InvoiceNinja logs.
/var/www/invoiceninja/storage/logs/
The second place to look is the VPS's error logs. Specifically check out the Nginx, php, mysql, and ufw logs.
/var/log
If you're having issues with installation commands not completing, it's almost certainly a permission or ownership issue, so double back to those sections of the guide and make sure you've entered those commands.
If your web app is loading, but sending 500 errors, it's often an issue with having compatible versions of everything installed. First check which version of php is supported by the version of Invoice ninja you're using. Then confirm you have the correct version and it's extensions installed. You'll also want to go back and make sure you've updated all the steps in this guide with the proper php version such as the Nginx config file and chron jobs.
That's a Wrap!
And as always, if you ever get stuck feel free to head over to Naughty Cat and shoot us a message; we're always happy to chat or help troubleshoot.
Or if you're excited about the setup, but not so excited about the prospect of deploying it, we also offer a deployment service as well as a customization service (to get that perfect invoice look). Reach out to us for more information or a quote.
We're also always available for consulting, web development, maintenance, hosting, and anything else web related!