Hello community.
Recently there have been many people having problems with upgrading their self-hosted version of InvoiceNinja to the most recent 5.10.x version as well as upgrading PHP to 8.2 or 8.3. I have put together an upgrade guide to try provide some assistance here.
Base Assumptions:
- You have command line access and a user with
sudorights - I have tested this with Ubuntu 22.04. It should work with Debian as well.
- It is not recommended to upgrade to
php8.3on versions of Ubuntu older than 22.04. Do so at your own risk.
- It is not recommended to upgrade to
- My test installation started with
php8.1, but this should also work for versions ofphpolder than that. - The test instance began from InvoiceNinja version 5.5.48
- PHP memory limit was tested with both
512Mand1024M. - This is only upgrading
php8.1>>php8.3and InvoiceNinja 5.5.48 >> 5.10.24 - This was using
nginxas the web server. I do not haveapache2setup. If you useapache2, you should not have to change your config file.
If you have any questions or problems, please ask and I will try to help.
Please note: as of writing this, it appears that if you have payment gateways configured on your instance, it breaks the installation, with minimal information indicating the problem. Please see the link below.
Update Ubuntu
First, we need to make sure that the current version of Ubuntu is fully updated.
sudo apt update && apt list --upgradable
If any packages are listed:
sudo apt upgrade
Remove and purge php8.1
First, let’s remove and then purge php8.1
sudo apt remove --purge php8.1
Next, let’s remove and then purge the php8.1 modules
sudo apt remove --purge php8.1-mysql php8.1-fpm php8.1-common php8.1-bcmath php8.1-gd php8.1-curl php8.1-zip php8.1-xml php8.1-mbstring php8.1-bz2 php8.1-intl php8.1-gmp
Just to be certain, next we remove the php8.1 directory
sudo rm -R /etc/php/8.1
Install new version of PHP and associated modules
Next, we will be installing php8.3. To do that on Ubuntu 22.04, we need to add the ppa. Some people argue against using PPAs, that is not for here. Specifically, this PPA is maintained by Ondrej Sury, the primary php maintainer and packager for Ubuntu. So this is no different than the packages found with Ubuntu 24.04.
sudo add-apt-repository ppa:ondrej/php
Then hit enter.
We have to remember to update apt to get access to the new repository.
sudo apt update
There is one dependency that is not installed by default in Ubuntu 22.04 that we need to install before installing php8.3.
sudo apt install apt-transport-https
We should always start by installing php8.3-cli first, otherwise unneeded SAPIs are installed if we just install php8.3 (or any other version) as an alphabetical list. The unused SAPIs can dramatically slow down php if they are installed and not needed.
sudo apt install --no-install-recommends php8.3-cli php8.3
Now we will install our other modules and packages.
sudo apt install php8.3-common php8.3-mysql php8.3-opcache php8.3-bcmath php8.3-imagick php8.3-soap php8.3-gd php8.3-mbstring php8.3-xml php8.3-curl php8.3-zip php8.3-gmp php8.3-intl
Please note that three required php modules that were previously independent packages have now been incorporated into php8.3-common. For reference, they are ctype, tokenizer, and iconv.
Since we are using nginx we need to reinstall php-fpm.
sudo apt install php8.3-fpm
Before moving on, we need to increase the upload_max_filesize and the memory_limit. The minimum memory_limit should be 512M, ideally change it to 1024M if you are able to do so.
We have to edit the php8.3-fpm config.
sudo nano /etc/php/8.3/fpm/php.ini
Use the nano search feature to reduce scrolling through the long document.
Use: ctrl - w then type upload_max_filesize
I prefer to increase this to 20M or higher.
Next increase the memory_limit. Again, use ctrl-w then type memory_limit. I change mine to 1024M.
We need to remember to reload php8.3-fpm.
sudo systemctl reload php8.3-fpm
From here, we need to edit our nginx config file to point to the new version of php.
sudo nano /path/to/nginx/invoiceninja.conf
Scroll down to or find the line that look like this and change it to be php8.3.
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_intercept_errors off;
fastcgi_buffer_size 16k;
fastcgi_buffers 4 16k;
Now it looks like this.
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_intercept_errors off;
fastcgi_buffer_size 16k;
fastcgi_buffers 4 16k;
Save and close. Then reload nginx.
sudo systemctl reload nginx
From here, we need to edit our cron job to point to the correct version of php.
Open the crontab for your www-data user.
sudo -u www-data crontab -e
It will probably look similar to this.
#InvoiceNinja
0 8 * * * /usr/bin/php8.1 /var/www/invoiceninja/artisan ninja:send-recurring > /dev/null
0 8 * * * /usr/bin/php8.1 /var/www/invoiceninja/artisan ninja:send-reminders > /dev/null
* * * * * /usr/bin/php8.1 /var/www/invoiceninja/artisan schedule:run >> /dev/null 2>&1
Update it to be /usr/bin/php8.3, then save and close the crontab.
That has now upgraded our system to php8.3. We are almost finished. Now to upgrade InvoiceNinja.
If you aren’t already there, move into your InvoiceNinja root directory. I use /var/www/invoiceninja, yours may be different. Please use your path.
cd /var/www/invoiceninja
We need to download the newest package. That can be found on GitHub. As of writing this, it is version 5.10.24. Copy the link to the latest tarball and we need to download it into our invoiceninja directory.
sudo wget https://github.com/invoiceninja/invoiceninja/releases/download/v5.10.24/invoiceninja.tar
The next step is to unpack the tarball. If you want it to display as it unpacks, make sure to include the -v flag. That would look like this:
sudo tar -xvf invoiceninja.tar
If you don’t care about watching it unpack, just use this.
sudo tar -xf invoiceninja.tar
You do not need to run both commands, it is only necessary to unpack it once. They are just two different options for doing this.
Now that it’s unpacked, let’s remove the tarball.
sudo rm invoiceninja.tar
We are almost finished. Let’s update our permissions.
sudo chown -R www-data:www-data /var/www/invoiceninja
sudo find ./ -type d -exec chmod 755 {} \;
Now, you are ready to install it with composer.
sudo -u www-data composer install
Supposedly, the next step is not necessary, but I had to do so in order to get my instance to reload. We migrate everything.
sudo -u www-data php artisan migrate
Lastly, we need to optimize our installation.
sudo -u www-data php artisan optimize
Then reboot. Maybe not necessary, but it can eliminate any issues.
sudo reboot
I found that after doing all this, I had to delete the cookies for my instance in order for the update to reload. On Firefox, you can just delete the individual cookies for your instance without affecting anything else that you have open. Unfortunately, I do not think this is possible on Chrome (or any derivatives like Brave or Edge). I do not have a Mac, so I don’t know about Safari.
I hope this helps.