Jump toUpdate content
How to deploy ERPNext 13 on Ubuntu 20.04 LTS (Focal Fossa)
ERPNext is a free and open-source ERP software designed for manufacturers, distributors and service companies. It comprises a full range of modules, including accounting, sales, CRM, purchasing, warehouse management, and inventory. Moreover, specialized modules are available, tailored to the needs of the education, 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. It is written in Python, based on the Frappé Framework, and uses a MariaDB database to store its data. The application is available under the GNU GPLv3 license and its source code is hosted on GitHub.
- You have an account and are logged into the Scaleway Console
- You have configured your SSH Key
- You have one of the following remote machines running Ubuntu Focal Fossa (20.04 LTS):
- You have sudo privileges or access to the root user
- You have configured an A-record pointing to your server’s IP address
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.
Log in to your remote machine using SSH:
ssh root@<remote_machine_ip>Note: If you are logging into a Dedibox server, you may not be able to log in as root but rather as the user you created during installation. In this case you may need to prefix commands in the rest of this section with `sudo`.
Update the apt package manager and upgrade the software already installed on the system:
apt update && 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.
Give the new user sudo privileges:
usermod -aG sudo mariecurie
Configure the locale of the system to
localectl set-keymap us && localectl set-locale LANG=en_US.utf8
Open the file
/etc/environmentin a text editor and add the following lines at the end of the file:
Save the file, exit the text editor
Reboot your instance using the
Wait a minute for the reboot to finish, then SSH back into your instance with the following command:
Switch to the
su - mariecurie
All following steps will be executed from the newly created user account
mariecurie and by using
Add a MariaDB mirror to the
aptconfiguration. ERPNext relies on MariaDB as database engine, but the version available by default in the repositories of Ubuntu is too old and not supported by ERPNext. The mirror 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] https://mariadb.mirror.liquidtelecom.com/repo/10.6/ubuntu focal main'
sudo apt update
Install MariaDB using the
sudo apt install mariadb-server-10.6 mariadb-client-10.6
Install the following packages which are required for ERPNext:
sudo apt install libmysqlclient-dev python3-mysqldb
Run the interactive setup tool to finalize the installation of MariaDB:
The setup tool asks you to enter the current MySQL password. As you 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, press Y to remove the test database and Y to reload the privileges to activate the new configuration.
Log in to the MySQL shell. We use a non-root user with superuser privileges:
Create a database named after the user that you want to use for connections to your MariaDB server. In this tutorial, we use
mariecurieagain, but you can choose whatever identifier you like.
CREATE DATABASE mariecurie;
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 'mariecurie'@'%' 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
Add the code below. Then save the file and exit the text editor:
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
innodb_read_only_compressed = FALSE
default-character-set = utf8mb4
Repeat step 10 for the file
sudo nano /etc/mysql/my.cnf
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 python3-testresources
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_14.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
wkhtmltopdfpackage in the
/tmpdirectory. ERPNext uses
wkhtmltopdfto convert HTML content into PDF files using the Qt WebKit rendering engine for generating printable invoices, quotations, and other reports.
cd /tmp && wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb
Install the downloaded package using
sudo dpkg -i wkhtmltox_0.12.6-1.focal_amd64.deb
Copy all the relevant binary files from the installation to the
sudo cp /usr/local/bin/wkhtmlto* /usr/bin/
Make those files executable:
sudo chmod a+x /usr/bin/wkhtmlto*
Return back into the
/homedirectory of the user:
ERPNext uses the caching features of Redis to increase database performance.
Install redis 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/mariecurie/.bench --depth 1 --branch master
sudo pip3 install -e /home/mariecurie/.bench
Increase Ubuntu’s file limit with the following command. This may be necessary for the Frappe Framework installation to succeed:
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/mariecuriewith the proper home path of your user:
bench init /home/mariecurie/frappe-bench --frappe-path https://github.com/frappe/frappe --frappe-branch version-13 --python python3
This step may take a while. Note that the script is able to recover from warnings such as
Command not being executed in bench directoryand
x is not a valid editable requirement.
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 mariecurie
SUCCESS: Bench /home/mariecurie/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-13
Run the following command to install any missing dependencies:
bench setup requirements
Create a new site for your ERPNext installation. Ensure you replace the parameters in the command as appropriate:
bench new-site your_erpnext_domain --admin-password 'a_secure_erpnext_admin_password' --mariadb-root-username mariecurie --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.
benchwith the following parameters. Replace
mariecuriewith the name of your user owning the production environment if necessary. Ensure you execute the command from the
frappe-benchdirectory of your user.
sudo bench setup production mariecurie
It will create 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:
certbotusing snap. To increase security, we will use TLS to encrypt the connection between clients and the server.Certbot is a tool that can manage the request and renewal of Let’s Encrypt certificates and the automatic configuration of Nginx.
sudo snap install certbot --classic
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 in the email address box, and the password that you 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. You can also choose to add a photo. 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. You can also choose to add a photo. Once done click Next to continue:
Enter 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 is now configuring 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. ERPNext provides wizards to customize all parameters towards the business needs of your company.
You have now installed, configured, and secured a complete ERPNext 13 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.