Jump toUpdate content
How to deploy ERPNext 12 on Ubuntu 18.04 LTS (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 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.
See our updated tutorial for installing ERPNext 13 on Ubuntu 20.04 Focal Fossa
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 of the commands we will be running later in this tutorial should not be carried out as root. Here, we call the new user
mariecurie, but you could call them
erpnextor 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 priveleges:
sudo usermod -aG sudo erpnext
Open the file
/etc/environmentin a text editor and add the following lines at the end of the file:
sudo nano /etc/environment
Configure the locale of the system to
localectl set-keymap us && localectl set-locale LANG=en_US.utf8
Save the file, exit the text editor, and reboot your Instance using the
All following steps will be executed from the newly created user account and by using
ERPNext relies on MariaDB as 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
aptconfiguration 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
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:
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:
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 the new user account and grant superuser privileges to it. Replace
strong_database_passwordin 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:
Exit the MariaDB shell:
Open the file
/etc/mysql/conf.d/50-server.cnfin 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:
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
default-character-set = utf8mb4
Restart the MariaDB server:
sudo service mysql restart
Install the following dependencies using the
aptpackage 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
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
sudo bash nodesource_setup.sh
Install NodeSource using
sudo apt install nodejs
sudo npm install -g yarn
ERPNext uses the
wkhtmltopdftool 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
/tmpdirectory 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
sudo dpkg -i wkhtmltox_0.12.5-1.bionic_amd64.deb
Copy all the relevant binary files to the
sudo cp /usr/local/bin/wkhtmlto* /usr/bin/
Make the files executable:
sudo chmod a+x /usr/bin/wkhtmlto*
Return to the
/homedirectory of the user:
ERPNext uses the caching features of Redis to increase database performance.
Install it using the
sudo apt install redis-server
Configure Redis to start automatically during system boot:
sudo systemctl enable redis-server
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.
benchGitHub repository using
git clone https://github.com/frappe/bench /home/timmy/.bench --depth 1 --branch master
sudo pip3 install -e /home/timmy/.bench
Increase Ubuntu’s file limit, which may be necessary for sucessfully 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/timmywith 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 completes, 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
Change into the directory into which
frappe-benchhas been installed:
Download ERPNext using the
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:
Updating DocTypes for frappe : [========================================]
Updating country info : [========================================]
Install ERPNext on your new site using
bench --site your_erpnext_domain install-app ERPNext
Once again you can follow the process in the status bar:
Updating DocTypes for ERPNext : [========================================]
Updating customizations for Address
Test the installation of the site using
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:
CTRL + Cin your terminal to stop the test environment.
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 IP’s trying to run bruteforce 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-benchdirectory of your user. Run
benchwith these parameters and replace
timmywith the name of your user owning the production environment:
sudo bench setup production timmy
It creates the following configuration files:
- Nginx: Two configuration files:
- Fail2Ban: One proxy jail (
/etc/fail2ban/jail.d/nginx-proxy.conf), and one filter configuration (
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.
- Nginx: Two configuration files:
Use TLS to encrypt the connection between clients and the server for increased security. For this purpose, install
certboton the machine.
certbotis 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
sudo add-apt-repository universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt update
sudo apt install certbot python3-certbot-nginx
certbotto 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:
- Congratulations! Your certificate and chain have been saved at:
Your key file has been saved at:
Open a web browser on your local computer and point it to
https://your_erpnext_domain/. The login page displays. Enter the user name 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:
You have now installed, configured, and secured a complete ERPNext 12 application. In the next step, you may want to configure it towards your business needs. For more information regarding the configuration and maintenance of the application, refer to the official ERPNext handbook.