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 upgradeSet 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.localThe 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/hosts127.0.0.1 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'
127.0.1.1 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-allroutersLog 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 nginxChange 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 https://dailydoseoftech.com 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 rootChange 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> FLUSH PRIVILEGES;
mysql> exit;Then restart your Mariadb server software.
sudo systemctl restart mariadb.serviceSet 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_installationThe following is an example of the output of this command.
chris@erpnext-v13:~$ sudo mysql_secure_installation
NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MariaDB
SERVERS IN PRODUCTION USE! PLEASE READ EACH STEP CAREFULLY!
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[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
[mysql] default-character-set = utf8mb4Then we need to restart the mariadb-server with:
sudo systemctl restart mariadb.serviceInstall 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 ~/.bashrcPATH=$PATH:~/.local/bin/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.
PART 2 - INSTALL
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.
Install Frappe-Bench
sudo -H pip3 install frappe-benchInitialise 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-benchThis command will do the following:
- Create a directory called
frappe-benchandfrappe-bench/sites,frappe-bench/appswithin it. - Setup a python virtual environment under
frappe-bench/env. - Create a
frappe-bench/configfolder to store redis configuration files. - Download
frappeapp andpip installit. - Install node packages.
- 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”
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.localYou 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
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 erpnextEnable 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 chrisComplete 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.
