Installing ERPNext 15 on Ubuntu 24.04

ERPNext is an amazing, free and open-source ERP system built using the Frappe Bench framework. It is scale-able, simple to use and quite beautiful. It is also quite difficult to install outside of the easy-installers, which might sometimes be necessary.

In my case, I have a production webserver running on Ubuntu 24.04 and using Virtualmin for vhost management. This requires me to manually install ERPNext and then make some changes to the specific configs to work niceley, however once the configuration is done, everything works perfectly. (Note, for my purposes I do not install mariadb or nginx, however I include them here for ease of use).

In order to install ERPNext on myt system, I will use DNS_Multitenant in bench.

In this tutorial, we will work through the steps necessary to implement ERPNext on a fresh Ubuntu 24.04 Install (Bare Metal or VM).

This how-to assumes that you are logged in as a user with sudo privileges and have already configured your DNS server to forward the relevant subdomain to the correct server.

Step 1 - Install Pre-requisite Software Packages:

1. Install the required packages:

sudo apt install git python3-dev python3-setuptools python3-pip python3-venv software-properties-common redis-server xvfb libfontconfig wkhtmltopdf libmysqlclient-dev mariadb-server mariadb-client curl supervisor nginx -y

1. Install the frappe-bench and ansible packages (note the --break-system-packages switch due to Python 3.11 no longer wanting you to use pip outside of venvs)

sudo pip3 install frappe-bench ansible --break-system-packages

Step 2 - Configure MariaDB

1. Configure MariaDB for use with Frappe-Bench:Edit your mariadb.cnf file to enable the Baracuda engine for innodb:

nano /etc/mysql/mariadb.conf.d/50-server.cnf

1. Insert the following below the [mysqld] block / edit the [mysqld] block if the options already exist:

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

1. Insert the following [mysql] block at the bottom of the file:

[mysql]
default-character-set = utf8mb4

1. Restart Mariadb

sudo service mysql restart

1. Run the MySQL Secure Installation Command and configure a root password:

sudo mysql_secure_installation

Step 3 – Create a Linux User to run your Bench (I user frappe for this example)

1. Create a Linux user with sudo priveleges to run your Bench instance:

adduser frappe

1. Configure with any password, however make a note in case you need to use it in future.

usermod -aG sudo frappe

Step 5 - Create a Bench instance for your ERPNext installation

1. Login with the frappe user you created in Step 4 above, alternatively su to it:

sudo su frappe

1. Make sure you are in your home directory:

cd ~/

1. Install Node.js and NPM (version 18 is required)

curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash

source ~/.profile

nvm install 18

1. Install the Yarn NMP Package:

sudo npm install -g yarn

1. Initiate a version 15 bench (This will create a folder in whichever folder you are now, so /home/frappe/frappe bench in this example):

bench init --frappe-branch version-15 frappe-bench

1. Switch to the newly created Bench instance folder, the name you chose at point 1 above will be the name of the bench folder:

cd frappe-bench

1. You can test whether it installed correctly with the following command, which should return the currently installed Bench version, 5.22.6 at the time of updating this how-to:

bench --version

1. Configure Bench to use the default Redis configuration:

bench set-config -g redis_cache redis://127.0.0.1:6379

bench set-config -g redis_queue redis://127.0.0.1:6379

bench set-config -g redis_socketio redis://127.0.0.1:6379

1. Enable DNS Multitenant:

bench config dns_multitenant on

Step 6 - Download the ERPNext app for Bench:

(Note, there are multiple apps you can install, payments, hrms, education, builder, loans, etc. You can essentially repeat the steps to install ERPNext to also get those apps)

bench get-app --branch version-15 erpnext

Step 7 - Create a site which will host your ERPNext instance:

Note that you should use the fqdn (Fully Qualified Domain Name) which you set up in DNS. For this example we will use erpnext.domain.com. The MariaDB root password you set in Step 2 will be used here.

1. Create the Bench site:

bench new-site erpnext.domain.com

1. Provide the MariaDB root password which you configured at Step 2 here.
2. During the installation, the installer will ask you to create an Administrator Password, make a note of the password you choose as you will need it to log in to ERPNext once it is installed.

Step 8 - Install the ERPNext App in your Site

1. Install the ERPNext App in the Bench Site you created in Step 7 above:

bench --site erpnext.domain.com install-app erpnext

Step 7 - Set up Bench for production use

1. In order to use your ERPNext installation in a production environment, you should automate starting, maintenance and various other tasks, luckily Bench can do this for you by making use of Supervisor, which we installed during Step 1 (Note the use of your bench user, frappe):

sudo bench setup production frappe

1. Enable Bench scheduler:

bench --site erpnext.domain.com enable-scheduler

BUGFIX - Supervisor fails to be automatically configured

There appears to be an issue with the installation wherein configuring production does not properly enable Supervisor in some cases. The workaround is to just point supervisor to the correct .conf file.

1. Stop Supervisor

sudo supervisorctl stop all

1. Create a synlink for the Frappe-Bench supervisorctl.conf file in the Supervisor conf.d folder:

sudo ln -sf /home/frappe/frappe-bench/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf

1. Reconfigure Supervisor:

sudo supervisorctl reread

sudo supervisorctl update

sudo supervisorctl start all

Note - Updating ERPNext

From time to time you might need to update ERPNext, the correct method is to login as the bench user you have created and entering the frappe-bench directory, then running the following command:

bench --update

Note - Updating Frappe Bench

From time to time you might need to update Frappe-Bench, the correct method is to login as the bench user you have created and running the following command:

sudo pip install --upgrade frappe-bench

Note - Restoring from backups

Make sure that you upload the backup files to the /tmp folder, note that there are three (3) files, being ...-database.sql.gz which contains the backup of your ERPNext data, ...-files.tar which contains your public files and ...-private-files.tar which contains your private files. Again, this must be run from your bench folder:

cd frappe-bench

bench --site erpnext.hrcity.co.za --force restore /tmp/...-database.sql.gz --with-private-files /tmp/...-private-files.tar --with-public-files /tmp/...-files.tar

Note - Restart from scratch

If you want to delete all the setup and configuration (Such as when testing) but don't want to go through all the steps of starting up a new setup, you can simply reset the database as follows:

cd frappe-bench

bench --site erpnext.domain.com --force reinstall