How to Install ERPNext version 13 on Debian 10 Buster

ERPNext is an open source Enterprise Resource Planning application that runs on Linux systems and is written in a combination of Python & Javascript. It also makes use of a mixture of other open source templating, caching and output systems. Mariadb or mysql databases can be used with the default nginx web server software.

In April 2021 the ERPNext foundation released ERPNext Version 13. This is a significant upgrade to the software including a complete UI makeover.

In this tutorial I will be showing the steps required to get a fully running installation of ERPNext on a fresh VM running Debian 10 with the logged in user as a member of the sudo group. In this example my hostname will be set to erpnext-v13.local and the username is chris. Replace these values when you see them with your hostname and username respectively.

Table of Contents

PART 1 - Setup

Ensure the system is up to date.

sudo apt update && sudo apt upgrade

Set the hostname of the system.

In the below example I have set my hostname to ‘erpnext-v13.local’. This machine is on my local network not connected to the internet. There are two commands to run to change the hostname in Debian 10. The first is the following:

sudo hostnamectl set-hostname erpnext-v13.local

The second is a command to set the hostname in the /etc/hosts file as below. The text in red is the line that I have edited from the orginal.

sudo nano /etc/hosts localhost
# In the line below I have changed the hostname to 'erpnext-v13.local'
# and then a space and then an alias to my hostname of 'erpnext-v13' erpnext-v13.local erpnext-v13

# The following lines are desirable for IPv6 capable hosts
::1 localhost ip6-localhost ip6-loopback ff02
::1 ip6-allnodes ff02::2 ip6-allrouters

Log out and log back in again to see the hostname changes.

Install all the required dependancies.

This will take a minute or two or three or four or ….. anyway….. wait for the whole thing to finish. One thing to note is that if you have Apache2 installed it will conflict with nginx (port conflicts) so make sure you either do not have apache installed or purge it from the system.

sudo apt install git python3-dev python3-setuptools python3-pip virtualenv mariadb-server libmariadb-dev nodejs npm redis-server wkhtmltopdf nginx

Change Mariadb password algorithm

Mariadb introduced a new  auth_socket plugin that makes it very difficult to enter your root password [impossible??] so we have to “hack” it back to the original password algorithm. Unbelievable I know…. It’s 2021 and we still have to do this in the name of ‘Security’ (I call FUD!). Hat tip to as the originator of this sequence of commands to fix this silliness.

Login to Mariadb as root (sudo will bypass password prompt)

sudo mysql -u root

Change to the mysql database and set the plugin to mysql_native_password for the root user.

mysql> USE mysql;
mysql> UPDATE user SET plugin='mysql_native_password' WHERE User='root'; 
mysql> exit;

Then restart your Mariadb server software.

sudo systemctl restart mariadb.service

Set up Mariadb-Server.

On a machine with a clean OS install you will not have a root password set yet so just hit enter at the first prompt and the set a new root password. This is extremely import not to forget so remember it somehow. The rest of the questions can be answered with the default Y unless you have specific reasons not to.

sudo mysql_secure_installation

The following is an example of the output of this command.

chris@erpnext-v13:~$ sudo mysql_secure_installation 


In order to log into MariaDB to secure it, we'll need the current
password for the root user.  If you've just installed MariaDB, and
you haven't set the root password yet, the password will be blank,
so you should just press enter here.

Enter current password for root (enter for none): 
OK, successfully used password, moving on...

Setting the root password ensures that nobody can log into the MariaDB
root user without the proper authorisation.

You already have a root password set, so you can safely answer 'n'.

Change the root password? [Y/n] y
New password: 
Re-enter new password: 
Password updated successfully!
Reloading privilege tables..
 ... Success!

By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them.  This is intended only for testing, and to make the installation
go a bit smoother.  You should remove them before moving into a
production environment.

Remove anonymous users? [Y/n] y
 ... Success!

Normally, root should only be allowed to connect from 'localhost'.  This
ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] y
 ... Success!

By default, MariaDB comes with a database named 'test' that anyone can
access.  This is also intended only for testing, and should be removed
before moving into a production environment.

Remove test database and access to it? [Y/n] y
 - Dropping test database...
 ... Success!
 - Removing privileges on test database...
 ... Success!

Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.

Reload privilege tables now? [Y/n] y
 ... Success!

Cleaning up...

All done!  If you've completed all of the above steps, your MariaDB
installation should now be secure.

Thanks for using MariaDB!

We need to edit the mariadb my.cnf file and add the following for frappe/erpnext to be able to work correctly with unicode symbols in the database.

sudo nano /etc/mysql/my.cnf
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql] default-character-set = utf8mb4

Then we need to restart the mariadb-server with:

sudo systemctl restart mariadb.service

Install yarn

sudo npm install -g yarn

Update our path

Add the following line to our ~/.bashrc file so our shell knows where to find our installation of the frappe-bench.  

nano ~/.bashrc

Log out and log back in again to see the $PATH changes.

This ends the setup part of the installation. In the following part we will install all the required applications to get our instance of ERPNext up and running.


Installing Frappe-Bench & Erpnext

Erpnext is an application that runs within a framework called Frappe. The following is from the Frappe Framework web site:

What is Frappe Framework?
Frappe is a full stack, batteries-included, web framework written in Python and Javascript.

It is the framework which powers ERPNext. It is pretty generic and can be used to build database driven apps.

If I was to venture a different description I would say that the Frappe Framework is a way of interacting with and displaying data from a database in forms, lists and reports that have a visual design that is focused, clear and modern.

Install Frappe-Bench

The Frappe Framework has a Python application that is used to install and manage applications that run within the framework. This application is called the frappe-bench. We need to install the bench before we can install the Frappe Framework itself and then ERPnext.
sudo -H pip3 install frappe-bench

Initialise an instance of Frappe

Once we have the Python application frappe-bench installed on our machine we can then initialise a new “bench”.

bench init --frappe-branch version-13 frappe-bench

This command will do the following:

  1. Create a directory called frappe-bench and frappe-bench/sitesfrappe-bench/apps within it.
  2. Setup a python virtual environment under frappe-bench/env.
  3. Create a frappe-bench/config folder to store redis configuration files.
  4. Download frappe app and pip install it.
  5. Install node packages.
  6. Build JS/CSS assets.


Each frappe-bench setup spawns it owns web, redis and node processes.

Next we ensure that the Python application is installed correctly.

cd frappe-bench
./env/bin/pip3 install -e apps/frappe/

Make a new “Site”

We now have a Python application called frappe-bench installed and we have initialised a new new “bench” and installed the application Frappe onto/into[??] the bench.

Our next step is to make a new site. This site can be called anything but we can call it by the domain name (or hostname) of the server. In this install I will be calling this site 121tech.local. If you have a Fully Qualified Domain Name and are wishing to have this instance fully connected to the internet then you can call it by that FQDN however it is only a reference. We have to configure the FQDN separately and this is out of the scope of this article.

bench new-site 121tech.local

You will be asked for the MySQL root password. You are also aksed to set the Administrator password for your new Frappe ‘Site’. You will need this to log into ERPNext.

Get ERPnext and install it into our site

 Run the following commands to download the latest version of ERPnext and ensure that it is installed correctly.
bench get-app --branch version-13 erpnext
./env/bin/pip3 install -e apps/erpnext/

Then install ERPnext into our newly created site.

bench --site 121tech.local install-app erpnext

Enable ERPNext “Production” status

The last step is to install the supervisor service and enable the production environment in the bench. Make sure you change the username ($USER) in the command sudo bench setup production $USER. The example below has my user name and will most likely cause you problems unless your user name is the same!

sudo apt install supervisor

sudo bench setup production chris

Complete your setup of ERPNext

You should now have a fully working installation of ERPnext running on your server. You can navigate to your hostname or your IP address to complete the post install setup via your web browser.

Chris Nuss

Chris Nuss

Father, partner, geek and farmer. I have spent a good deal of my life looking at how things work. I am prepared to get into the back end of most things, learning, testing and making mistakes. I savour the gold that is there.

I work out practical systems that help us as humans, whether it is designing a web site or working out the best fence line for a keyline farm plan. Little bit by little bit I am finding the spirit and soul in all things.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.