Installing ERPNext 15 on Debian 12

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 do not play nice with Debian.

In my case, I have an LXC Container on Proxmox VE, running Debian 12, MariaDB and Nginx, already serving several apps configured to various subdomains, which means that this existing server is ideally suited to install the ERPNext website on, this is achieved by using DNS_Multitenant in bench.

It should be noted that if, like me, you use Proxmox VE with an LXC Container, you will need to enable nested virtualization in the container in order for redis-server to work. Simply edit the Container Config File (/etc/pve/lxc/.conf) and add a line at the bottom: features: nesting=1 (Or enable nesting in the Proxmox WebUI).

In this tutorial, we will work through the steps necessary to implement ERPNext on a fresh Debian Install (LXC Container but works on Bare Metal or VM).

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

Step 1 - Install Pre-requisite Software Packages:

Install the required packages:

apt install build-essential curl git python3-dev python3-setuptools python3-pip python3-distutils python3-venv supervisor software-properties-common mariadb-server mariadb-client libmariadb-dev nginx xfonts-75dpi -y

Install wkhtmltopdf with patched qt

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb

dpkg -i wkhtmltox_0.12.6.1-3.bookworm_amd64.deb

Install Node.js and NPM (version 18+ is required but 20 is supported)

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

source ~/.profile

nvm install 18

Install the Yarn NMP Package:

npm install -g yarn

Step 2 - Configure MariaDB

• 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

• Insert the following below the [mysqld] block:

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

• Insert the following [mysql] block:

[mysql]
default-character-set = utf8mb4

• Restart Mariadb

systemctl restart mariadb

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

mysql_secure_installation

Step 3 – Create a Linux User to run your Bench

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

adduser frappe

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

usermod -aG sudo frappe

Step 4 - Install Bench

• Login to Debian with your newly created bench user, or, as root, su to the bench user:

su frappe

• Install Bench:

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

Step 5 - Create a Bench instance for your ERPNext installation

• Create a Bench instance, name it anything you'd like, however I am going to use frappe-bench for ease of reference:Make sure you are in your home directory:

cd

• Initiate a version 15 bench:

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

• 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

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

bench --version

• 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

Step 6 - Download the ERPNExt app for Bench:

• If you chose to go with the standard (Developer) branch during step 5:

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 User you created at point 2 in Step 2 can be substituted if you did not use bench as the username for your instance.
• Create the Bench site:

bench new-site erpnext.domain.com

Provide the MariaDB root password which you configured at Step 2 here.

• 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

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

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

• You can now manually start Bench using the command bench start, however we won't be doing that as we want it to start automatically, which is done by setting up Bench for Production Use.

Step 7 - Set up Bench for production use

• 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:

sudo bench setup production bench

• Enable Bench scheduler:

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

Step 8 - BUGFIX - Supervisor

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

• Stop Supervisor

sudo supervisorctl stop all

• 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

• Reconfigure Supervisor:

sudo supervisorctl reread

sudo supervisorctl update

sudo supervisorctl start all

Step 9 - Fix CSS

• Due to the way in which Debian 12 works wit permissions and python3, we need to fix the permissions of the frappe user folder:
• sudo chmod 701 /home/frappe

And you are done, now simply point your browser at the site you configured: http://erpnext.domain.com/ and it should show you the login page. Use Administrator as the username and the password which you configured during point 3 in Step 7.

Edit - Updating your Bench Sites

When you need to update your Bench sites to the latest version, login as the bench user and cd to your bench instance folder:

cd frappe-bench

bench update

Edit - 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

Edit - 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

Edit - 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