Installing ERPNext 14 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 git python3-dev python3-setuptools python3-pip python3-distutils python3-venv supervisor software-properties-common mariadb-server mariadb-client xvfb libfontconfig1 wkhtmltopdf libmariadb-dev curl nginx sudo build-essential --no-install-recommends
 -y

Install Node.js and NPM (version 16+ is required)

curl -sL https://deb.nodesource.com/setup_16.x | bash -

apt install nodejs npm --no-install-recommends -y

Install the Yarn NMP Package:

npm install -g yarn

Install Redis from the Redis repo (The version shipping with Debian is outdated)

curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list

apt install redis-server --no-install-recommends
 -y

systemctl enable --now redis-server

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 14 bench:
  bench init --frappe-branch version-14 frappe-bench
Make sure that the bench folder is executable:
chmod -R o+rx ./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-14 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

Installing ERPNext 14 on Debian 12

Comments

Leave a Reply Cancel reply