Deploying ERPNext 12 on Ubuntu 18.04 LTS (Bionic Beaver)

Reviewed on 03 October 2024 • Published on 28 July 2020

ERPNext
erp
odoo
Ubuntu
Bionic-Beaver

ERPNext is a free and open-source ERP software designed to be used by manufacturers, distributors, and service companies. It includes a full range of modules, including accounting, sales, CRM, purchasing, warehouse management, and inventory. Moreover, specialized modules are available tailored to schools, healthcare, agriculture, and non-profit sectors. It uses a MariaDB database to store its data, is written in Python, and is based on the Frappé Framework. The application is released under the GNU GPLv3 license, and its source code is hosted on GitHub.

In this tutorial, you will learn how to install and configure ERPNext 12 on Ubuntu 18.04 (Bionic Beaver) on a Scaleway Dedibox dedicated server.

Tip

See our updated tutorial for installing ERPNext 13 on Ubuntu 20.04 Focal Fossa.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console
Owner status or IAM permissions allowing you to perform actions in the intended Organization
An SSH key
A Scaleway Dedibox dedicated server running on Ubuntu 18.04 (Bionic Beaver)
sudo privileges or access to the root user
Configured an A-record pointing to your server’s IP address

Configuring locales

Start by configuring the system’s keyboard mapping for the console as well as the language and character encoding on the host. This step is required to avoid any possible troubles during the ERPNext installation process and does not affect the UI language you will use on the ERPNext web interface.

Update the APT package manager and upgrade the software already installed on the system:

sudo apt update && sudo apt upgrade -y

Create a new user. Some commands we will run later in this tutorial should not be carried out as root. Here, we call the new user mariecurie, but you could call them erpnext or whatever you like. Enter a password for them when prompted. You can leave the user information at default values if you wish.

sudo adduser erpnext

Give the new user sudo privileges:

sudo usermod -aG sudo erpnext

Open the file /etc/environment in a text editor and add the following lines at the end of the file:

sudo nano /etc/environment

[...]
LC_ALL=en_US.UTF-8
LC_CTYPE=en_US.UTF-8
LANG=en_US.UTF-8

Configure the locale of the system to en_US.utf8:

localectl set-keymap us && localectl set-locale LANG=en_US.utf8

Save the file, exit the text editor, and reboot your Instance using the reboot command.

All the following steps will be executed from the newly created user account and by using sudo.

Installing MariaDB

ERPNext relies on MariaDB as a database engine, but the version available by default in the repositories of Ubuntu 18.04 LTS is too old and not supported by ERPNext. Therefore, add a MariaDB mirror to the apt configuration which allows us to install a more recent version on the system:

sudo apt install software-properties-common
sudo apt-key adv --fetch-keys 'https://mariadb.org/mariadb_release_signing_key.asc'
sudo add-apt-repository 'deb [arch=amd64,arm64,ppc64el] http://ftp.igh.cnrs.fr/pub/mariadb/repo/10.4/ubuntu bionic main'
sudo apt update

Install MariaDB using the apt package manager:

sudo apt install mariadb-server-10.4 mariadb-client-10.4

Install the following packages which are required for ERPNext:

sudo apt install libmysqlclient-dev python3-mysqldb

Finalize the installation of MariaDB by running the interactive setup tool:

sudo mysql_secure_installation

The setup tool asks you to enter the current MySQL password. As we have a fresh installation, no password is configured yet, press Enter to continue. When asked to set a root password for MySQL, press Y and enter a secret password and its confirmation. Press Y to remove anonymous users when prompted, then press Y again to disallow root login, confirm removing the test database, and reload the privileges to activate the new configuration.

Use a non-root user with superuser privileges to connect to the database with ERPNext. Log in to the MySQL shell:

sudo mysql

Create a database named after the user that you want to use for connections to your MariaDB server. In this tutorial, we use timmy, but you can choose whatever identifier you like.

CREATE DATABASE timmy;

Create a new user account and grant superuser privileges to it. Replace strong_database_password in the following command with a secure password for the user:

GRANT ALL PRIVILEGES ON *.* TO 'timmy'@'%' IDENTIFIED BY 'strong_database_password' WITH GRANT OPTION;

Flush the privileges to activate the new user account:

FLUSH PRIVILEGES;

Exit the MariaDB shell:

EXIT;

Open the file /etc/mysql/conf.d/50-server.cnf in a text editor:

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

Make sure that the character set is set to utfmb4_unicode_ci. Then save the file and exit the text editor:

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

Restart the MariaDB server:

sudo service mysql restart

Setting up ERPNext

Installing prerequisites

Install the following dependencies using the apt package manager before continuing with the installation of ERPNext:

sudo apt install -y apt-transport-https build-essential curl mariadb-client python3-setuptools python3-dev python3-mysqldb libffi-dev python3-pip libcurl4 dnsmasq fontconfig git htop libcrypto++-dev libfreetype6-dev liblcms2-dev libldap2-dev libcups2-dev pv libjpeg8-dev libtiff5-dev tcl8.6-dev tk8.6-dev libssl-dev libdate-manip-perl zlib1g-dev libsasl2-dev libwebp-dev libxext6 libxrender1 libxslt1-dev libxslt1.1 libffi-dev logwatch ntpdate postfix python3-dev python-tk screen vim xfonts-75dpi xfonts-base

Continue to install the required Python dependencies and upgrade pip:

sudo -H python3 -m pip install --upgrade setuptools cryptography psutil

Download a script to add the NodeSource repository to your system and save it locally:

curl -sL https://deb.nodesource.com/setup_12.x -o nodesource_setup.sh

Run the script to configure the NodeSource repository with the apt package manager:

sudo bash nodesource_setup.sh

Install NodeSource using apt:

sudo apt install nodejs

Install yarn using npm:

sudo npm install -g yarn

ERPNext uses the wkhtmltopdf tool to convert HTML content into PDF files using the Qt WebKit rendering engine for generating printable invoices, quotations, and other reports. Install it by changing into the /tmp directory and downloading the required package:

cd /tmp && wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.bionic_amd64.deb

Install the downloaded package using dpkg:

sudo dpkg -i wkhtmltox_0.12.5-1.bionic_amd64.deb

Copy all the relevant binary files to the /usr/bin directory:

sudo cp /usr/local/bin/wkhtmlto* /usr/bin/

Make the files executable:

sudo chmod a+x /usr/bin/wkhtmlto*

Return to the /home directory of the user:

cd /home/timmy

Installing Redis™

ERPNext uses the caching features of Redis™ to increase database performance.

Install it using the apt package manager:

sudo apt install redis-server

Configure Redis™ to start automatically during system boot:

sudo systemctl enable redis-server.service

Installing the Frappe Bench CLI

As the ERPNext stack’s major prerequisites are installed, go on by installing the Frappe bench command-line interface. It has been designed to assist users with installing, configuring, and managing applications using the Frappe Framework, like ERPNext.

Clone the bench GitHub repository using git:
```
git clone https://github.com/frappe/bench /home/timmy/.bench --depth 1 --branch master
```

Install the bench CLI using pip3:

sudo pip3 install -e /home/timmy/.bench

Installing the Frappe framework

Increase Ubuntu’s file limit, which may be necessary for successfully installing the Frappe Framework. Use the following command:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Initialize the Frappe framework using the following command. Remember to replace /home/timmy with the proper home path of your user:

bench init /home/timmy/frappe-bench --frappe-path https://github.com/frappe/frappe --frappe-branch version-12 --python python3

Once the installation is completed, you will see an output like the following example:

✨  Done in 94.7s
Done in 96.74s.
INFO:bench.utils:setting up backups
no crontab for timmy
SUCCESS: Bench /home/timmy/frappe-bench initialized

Installing ERPNext web application

Change into the directory into which frappe-bench has been installed:

cd /home/timmy/frappe-bench

Download ERPNext using the bench command-line interface:

bench get-app ERPNext https://github.com/frappe/erpnext --branch version-12

Create a new site for your ERPNext installation:

bench new-site your_erpnext_domain --admin-password 'a_secure_erpnext_admin_password' --mariadb-root-username timmy --mariadb-root-password 'your_mariadb_root_password'

The site creation may take a moment, and you can follow the progress in the status bars:

Installing frappe...
Updating DocTypes for frappe        : [========================================]
Updating country info               : [========================================]

Install ERPNext on your new site using bench:

bench --site your_erpnext_domain install-app ERPNext

Once again you can follow the process in the status bar:

Installing ERPNext...
Updating DocTypes for ERPNext       : [========================================]
Updating customizations for Address

Test the installation of the site using bench:
```
bench start
```
Bench will deploy a test environment and you can access ERPNext at http://your_erpnext_domain:8000. If you open this URL in your web browser, the ERPNext login screen displays:

Press CTRL + C in your terminal to stop the test environment.

Getting production-ready

Our test environment has proven that our ERPNext installation is working, but some additional steps are required to secure it and make it production-ready. We are again using the bench command-line tool to install the following tools on the machine:

Fail2Ban, a useful tool that analyses server log files for recurring patterns of failures, allowing us to block IPs trying to run brute force attacks against a server.
Nginx, a versatile web server that will be used as a proxy to redirect all requests on the standard HTTP (Port 80) and HTTPS (Port 443) to the ERPNext application listening on port 8000.
Supervisor, a service that ensures all required processes of ERPNext are constantly up and running. In case of any failure, it will restart them.

Execute the following command from the frappe-bench directory of your user. Run bench with these parameters and replace timmy with the name of your user owning the production environment:

sudo bench setup production timmy

It creates the following configuration files:

Nginx: Two configuration files: /etc/nginx/nginx.conf, and /etc/nginx/conf.d/frappe-bench.conf
Fail2Ban: One proxy jail (/etc/fail2ban/jail.d/nginx-proxy.conf), and one filter configuration (/etc/fail2ban/filter.d/nginx-proxy.conf)

The default values configured in these files are suitable for an essential start and the goals of this tutorial. However, depending on your workload, you may tweak them further. 2. Use TLS to encrypt the connection between clients and the server for increased security. For this purpose, install certbot on the machine. certbot is a tool that can manage the request and renewal of Let’s Encrypt certificates and the automatic configuration of Nginx. Add the certbot packet archive to the apt package manage:

sudo add-apt-repository universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt update

Install certbot using apt:

sudo apt install certbot python3-certbot-nginx

Run certbot to obtain a Let’s Encrypt TLS certificate and to reconfigure Nginx to use it:

sudo certbot --nginx

When prompted, enter your email address, agree to the terms of service, and choose to redirect all requests to HTTPS. Certbot will then request the certificate and update the Nginx configuration accordingly. A message displays once the configuration is done:

IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
  /etc/letsencrypt/live/your_erpnext_domain/fullchain.pem
  Your key file has been saved at:
  /etc/letsencrypt/live/your_erpnext_domain/privkey.pem
[...]

Configuring ERPNext

Open a web browser on your local computer and point it to https://your_erpnext_domain/. The login page displays. Enter the username Administrator and the password defined during the setup. Then click Login:

You are now logged into the ERPNext installation wizard.
Choose your language, then click Next:
Set your country, timezone, and currency, then click Next:
Configure your first user account. Enter your full name, your e-mail address, and a secret password. Click Next to proceed:
Select your domains. Domains include a predefined set of modules that are designed for different usage types. You can choose one or several domains. If you are not sure which to one to choose, select Distribution and click Next to go to the following step:
Configure your brand: Enter your company name and an abbreviation of it. Once done click Next to continue:
Enter the information about what your company does, your bank’s name, the charts template to use, as well as information on your financial year. Then click Complete Setup:

ERPNext configures your parameters. The configuration may take a moment. The status bar gives you information about the progress of this task:

The ERPNext dashboard displays. You can see an overview of all available categories:
Click Getting Started to launch the configuration of your newly installed application. ERPNext provides wizards to customize all parameters towards the business needs of your company:

Going further

You have installed, configured, and secured a complete ERPNext 12 application. In the next step, you may want to configure it to your business needs. For more information regarding the configuration and maintenance of the application, refer to the official ERPNext handbook.