How To Install an ERPNext Stack on Ubuntu 18.04

ERPNext is an Enterprise Resource Planning (ERP) suite that leverages the power and flexibility of open-source technologies. It excels at managing core business processes such as finance, sales, human resources, manufacturing, purchases, services, helpdesk needs, and more. Among the benefits of implementing a system like ERPNext are:

• Better productivity by automating repetitive business processes
• Improved IT efficiency by sharing a database for all departments within the company
• Better decision-making thanks to an integral vision of how business units relate to each other

ERPNext is based on Frappe, a full-stack web application framework written in Python that takes full advantage of the Node/JavaScript runtime environment and uses MariaDB as its database backend. One of the many advantages of Frappe-based applications, like ERPNext, is the bench command-line utility. The bench CLI saves administrators time by automating tasks such as installing, updating, configuring, and managing multiple Frappe/ERPNext sites.

In this tutorial you will install and configure an ERPNext stack on one server running Ubuntu 18.04. This will allow you to configure your stack for various development or production environments depending on your needs, and it will prepare you to build a more complex, fault-tolerant architecture.

• One Ubuntu 18.04 server with at least 4 GB of RAM and a non-root sudo user. You can set up your server and user by following the Ubuntu 18.04 initial server setup guide.

• A fully registered domain name with an A record pointed to your server. If you are using a DigitalOcean Droplet then you can follow this guide to properly set up your DNS. This tutorial will use your_domain throughout.

Although configuring a firewall for development is optional, for production it is a mandatory security practice.

You will need to open the following ports on your ERPNext server:

• 80/tcp and 443/tcp for HTTP and HTTPS respectively
• 3306/tcp for MariaDB connection (recommended only if you need remote access to database)
• 143/tcp and 25/tcp for IMAP and STMP respectively
• 22/tcp for SSH (if you have not already enabled OpenSSH)
• 8000/tcp for development testing before deploying your site

To open multiple ports at once you can use the following command:

sudo ufw allow 22,25,143,80,443,3306,8000/tcp

Alternatively, you can allow connections from specific IP addresses on specific ports using this command:

sudo ufw allow from server_IP to any port port_number

After opening all necessary ports enable the firewall:

sudo ufw enable

After enabling the firewall, confirm the status of your open ports:

sudo ufw status

For more information regarding the firewall setup please read our guide How To Set Up a Firewall with UFW on Ubuntu 18.04.

Setting up a proper firewall is the first of two preliminary steps. Now you will configure keyboard mapping and character encoding on your server.

It’s highly recommended that you configure keyboard mapping for the console as well as the language and the character encoding on your host. This is necessary to avoid possible issues during the ERPNext 12 installation process. Take note that this configuration has nothing to do with the UI language on your actual ERPNext platform, but with the system locale configuration.

First, update your server:

sudo apt update

Now configure keymap, language, and character encoding:

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

The localectl utility is used by Ubuntu 18.04 and other Linux distributions to control and change system-wide locale and keyboard layout settings before the user logs in, which is exactly what ERPNext 12 requires.

You will also need to add the following lines to your /etc/environment file. Use nano or your preferred text editor to open the file:

sudo nano /etc/environment

Now add the following content:

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

Save and close the file.

Reboot your server to apply all changes:

sudo reboot

Give your server a few minutes to reboot and then ssh back inside. You are now ready to install your database.

Now you will add MariaDB to your server stack. ERPNext 12 requires MariaDB 10.2+, but the version included in Ubuntu 18.04’s official repository is 10.1, which means that you will need to install a higher version. For the purposes of this guide, you will use the latest stable release of MariaDB, which, at the time of this writing, is version 10.4.

To install MariaDB 10.4 on Ubuntu 18.04 you will need to add the appropriate signature key and repository. You can find this information on the MariaDB Foundation’s repository wizard. Visit this URL in your web browser. Now, under 1. Choose a Distro, click Ubuntu. A second column titled 2. Choose a Release will appear. Beneath this title click 18.04 LTS “bionic”. A third column titled 3.Choose a Version will then appear. Beneath this click 10.4 stable. A third column titled 4.Choose a Mirror will then appear. Choose a mirror based on your location, and then MariaDB will populate the appropriate commands for your custom installation.

Run the three populated commands, which will properly add the MariaDB repository and key. Your own commands will look something like this:

sudo apt-get 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://mirror.klaus-uwe.me/mariadb/repo/10.4/ubuntu bionic main'

Once you have finished adding the repository, install MariaDB:

sudo apt install mariadb-server

After installing mariadb-server, install the following packages:

sudo apt install libmysqlclient-dev python3-mysqldb

ERPNext 12 is a Python application and thus it requires the python3-mysqldb library for database management. Concerning libmysqlclient-dev, mariadb-client, and libmariadbclient18: those packages let users communicate with the MariaDB service. ntpdate and libdate-manip-perl are used by ERPNext for server time synchronization.

Next, add a basic layer of security to the MariaDB server by running the mysql_secure_installation script:

sudo mysql_secure_installation

The mysql_secure_installation script will prompt you with several questions:

• The first prompt will ask you about the root password, but since there is no password configured yet, press ENTER.
• Next, you will have to decide on using Unix authentication or not. Answer Y to accept this authentication method.
• When asked about changing the MariaDB root password, answer N. Using the default password along with Unix authentication is the recommended setup for Ubuntu-based systems because the root account is closely related to automated system maintenance tasks.
• The remaining questions have to do with removing the anonymous database user, restricting the root account to log in remotely on localhost, removing the test database, and reloading privilege tables. It is safe to answer Y to all those questions.

After completing the mysql_secure_installation script, MariaDB will start running using its default configuration. The standard ERPNext installation uses MariaDB’s root user for all database operations. While that approach may be convenient on single server setups, it is not considered a good security practice. Therefore, in the next section you will learn how to avoid this issue by creating a new user with special privileges.

sudo mysql

CREATE DATABASE sammy;

SHOW DATABASES;

Output
+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| performance_schema |
| sammy             |
+--------------------+

GRANT ALL PRIVILEGES ON *.* TO 'sammy'@'%' IDENTIFIED BY 'mariadb_password' WITH GRANT OPTION;

SELECT host, user, Super_priv FROM mysql.user;

Output
+-----------+-------+------------+
| Host      | User  | Super_priv |
+-----------+-------+------------+
| localhost | root  | Y          |
| localhost | mysql | Y          |
| %         | sammy | Y          |
+-----------+-------+------------+
3 rows in set (0.001 sec)

FLUSH PRIVILEGES;

exit

With MariaDB installed and secured it’s time to fine-tune it for ERPNext connections.

First, stop mariadb.service:

sudo systemctl stop mariadb

Now use nano or your favorite text editor to create a MariaDB configuration file called settings.cnf:

sudo nano /etc/mysql/conf.d/settings.cnf

Now add ERPNext’s configuration template:

[mysqld]

# GENERAL #
user                           = mysql
default-storage-engine         = InnoDB
socket                         = /var/lib/mysql/mysql.sock
pid-file                       = /var/lib/mysql/mysql.pid

# MyISAM #
key-buffer-size                = 32M
myisam-recover                 = FORCE,BACKUP

# SAFETY #
max-allowed-packet             = 256M
max-connect-errors             = 1000000
innodb                         = FORCE

# DATA STORAGE #
datadir                        = /var/lib/mysql/

# BINARY LOGGING #
log-bin                        = /var/lib/mysql/mysql-bin
expire-logs-days               = 14
sync-binlog                    = 1

# REPLICATION #
server-id                      = 1

# CACHES AND LIMITS #
tmp-table-size                 = 32M
max-heap-table-size            = 32M
query-cache-type               = 0
query-cache-size               = 0
max-connections                = 500
thread-cache-size              = 50
open-files-limit               = 65535
table-definition-cache         = 4096
table-open-cache               = 10240

# INNODB #
innodb-flush-method            = O_DIRECT
innodb-log-files-in-group      = 2
innodb-log-file-size           = 512M
innodb-flush-log-at-trx-commit = 1
innodb-file-per-table          = 1
innodb-buffer-pool-size        = 5462M
innodb-file-format             = barracuda
innodb-large-prefix            = 1
collation-server               = utf8mb4_unicode_ci
character-set-server           = utf8mb4
character-set-client-handshake = FALSE
max_allowed_packet             = 256M

# LOGGING #
log-error                      = /var/lib/mysql/mysql-error.log
log-queries-not-using-indexes  = 0
slow-query-log                 = 1
slow-query-log-file            = /var/lib/mysql/mysql-slow.log

[mysql]
default-character-set = utf8mb4

[mysqldump]
max_allowed_packet=256M

!includedir /etc/mysql/mariadb.conf.d/

Save and close the file. For more detailed information about these configurations, review this template file on ERPNext’s Github repo. This is a useful starting point for exploring these options.

Next, create another file called erpnext.cnf:

sudo nano /etc/mysql/mariadb.conf.d/erpnext.cnf

Add the following content to the file:

[mysqld]
pid-file        = /var/run/mysqld/mysqld.pid
socket          = /var/run/mysqld/mysqld.sock
bind-address    = 0.0.0.0

The first file, /etc/mysql/conf.d/settings.cnf, complements and also overrides a few values included in the default MariaDB configuration located at /etc/mysql/my.cnf. This file gives you a curated template that greatly enhances database performance for ERPNext. Keep in mind though that while this template is a great starting point, nothing prevents you from improving MariaDB’s performance even further by adjusting these parameters to fit your needs.

The second file, /etc/mysql/mariadb.conf.d/erpnext.cnf, also overrides some values by introducing specific information regarding your database connection.

sudo systemctl start mariadb

mysql --user sammy --password mariadb_password --host=localhost --protocol=tcp --port=3306 test

Output
mysql  Ver 15.1 Distrib 10.4.13-MariaDB, for debian-linux-gnu (x86_64) using readline 5.2
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Usage: mysql [OPTIONS] [database]

Default options are read from the following files in the given order:
/etc/my.cnf /etc/mysql/my.cnf ~/.my.cnf

...

  --ssl-verify-server-cert
                      Verify server's "Common Name" in its cert against
                      hostname used when connecting. This option is disabled by
                      default.
  -t, --table         Output in table format.
  --tee=name          Append everything into outfile. See interactive help (\h)
                      also. Does not work in batch mode. Disable with
                      --disable-tee. This option is disabled by default.
  -u, --user=name     User for login if not current user.
  -U, --safe-updates  Only allow UPDATE and DELETE that uses keys.
  -U, --i-am-a-dummy  Synonym for option --safe-updates, -U.
  -v, --verbose       Write more. (-v -v -v gives the table output format).

...

max-join-size                     1000000
secure-auth                       FALSE
show-warnings                     FALSE
plugin-dir                        (No default value)
default-auth                      (No default value)
binary-mode                       FALSE
connect-expired-password          FALSE

sudo systemctl restart mariadb

sudo systemctl enable mariadb

Now that your database backend is ready you can continue setting up your ERPNext web application. In this section, you will learn how to install and configure all components required by ERPNext 12 and then install the application itself.

Start by preparing the server with all the system packages required by ERPNext 12. Install system-wide dependencies using the following command:

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

The DEBIAN_FRONTEND=noninteractive variable has been passed to the installation command in order to avoid Postfix prompts. For detailed information regarding Postfix configuration please read our guide on How To Install and Configure Postfix on Ubuntu 18.04

Next, update pip3 and then install the latest versions of three additional Python modules required by ERPNext:

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

Now that you have installed all necessary global dependencies, you will now install all the services and libraries required by ERPNext 12.

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

sudo nano nodesurce_setup.sh

sudo bash nodesource_setup.sh

sudo apt install nodejs

sudo npm install -g yarn

cd /tmp

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

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

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

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

sudo apt install redis-server

sudo systemctl enable redis-server

Now that you have installed all of ERPNext’s stack requirements you can unleash the flexibility of Frappe’s bench command-line utility. The bench CLI was designed with the purpose of assisting users in the process of installing, setting up, and managing applications like ERPNext that are based on the Frappe Framework. In the coming sections, you will install the bench CLI and then use it to complete the process of setting up ERPNext 12.

Make sure that the Frappe user (in this case sammy) has the proper rights on its home directory:

sudo chown sammy -R /home/sammy

Now clone the frappe/bench repository to your home directory. Remember to replace sammy with your system username:

git clone https://github.com/frappe/bench /home/sammy/.bench --depth 1 --branch master

Install the bench CLI:

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

This guide is assuming that you are installing ERPNext 12 for testing/production scenarios and thus that you are using the master branch. But if your intention is to develop applications or custom ERPNext modules, then the develop branch might be a better option. In either case, you are now prepared to install the Frappe Framework. This will be your final step before installing ERPNext itself.

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

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

Output
...
Done in 82.23s.
INFO:bench.utils:setting up backups
no crontab for sammy
SUCCESS: Bench /home/sammy/frappe-bench initialized

In this section, you will set up a Frappe-based site and then install the ERPNext 12 application on it.

Change to the directory where Frappe was initialized.

cd /home/sammy/frappe-bench

Now download ERPNext 12 from its repository using the bench CLI:

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

Next, create the new site, replacing your_domain with the domain that you have associated with this server’s IP:

bench new-site your_domain --admin-password 'erpnext_admin_password' --mariadb-root-username sammy --mariadb-root-password 'mariadb_password'

Let’s take a moment to review the options used in the command above:

• bench new-site creates a new site based on the Frappe Framework.
• your_domain is the name for the new site. Make sure that your domain’s DNS has an A record pointing at your server’s IP.
• erpnext_admin_password is the desired password for ERPNext’s Administrator user. Keep this password in a safe place—you will need it shortly.
• mariadb_password is the password that you created at the beginning of the guide for the MariaDB user sammy.

Following this, install the ERPNext application onto the site:

bench --site your_domain install-app erpnext

Once the installation completes you will have a working ERPNext 12 application. Now let’s test it using a bench command:

bench start

The above will initiate a real-time monitoring console showing you various messages regarding the webserver and other services. Open a web browser and navigate to localhost:8000 (for local installations) or your_domain:8000 (if you are using a remote server). You will see the ERPNext login screen (we will proceed with login and setup in a later step, once we have made our site production-ready).

After visiting your test deployment, return to your terminal and press CTRL+C. This will stop ERPNext and exit the monitoring console.

If your main goal is creating modules or modifying ERPNext 12, then you could stop at this point. No more components are needed for development purposes. However, if what you need is a production-ready system that does not require a manual initialization, then you will need to install and configure a few additional components. This is your next step.

Although ERPNext 12 application is ready, the system as a whole it’s not completely prepared for production yet. To ensure ERPNext reliability and security you will need to enable a few additional services:

• Fail2ban provides an extra layer of protection against brute force attempts from malicious users and bots.
• Nginx will be mainly used as a web proxy, redirecting all traffic from port 8000 to port 80 (HTTP) or port 443 (HTTPS)
• Supervisor this service ensures that ERPNext key processes are constantly up and running, restarting them as necessary.

Up to this point, you have installed and configured ERPNext 12 manually, which has allowed you to customize the process to match any particular use case. Nevertheless, for the rest of the production setup, you can leverage the convenience of the bench CLI and let it automate the installation and configuration of these remaining services.

Ensure you are in the Frappe working directory:

cd /home/sammy/frappe-bench

Now use the following command to finish setting up ERPNext 12 for production:

sudo bench setup production sammy --yes

The above will install and configure Nginx, Supervisor, and Fail2Ban and set sammy as the production environment owner.

The configuration files created by the bench command are:

• Two Nginx configuration files located at /etc/nginx/nginx.conf and /etc/nginx/conf.d/frappe-bench.conf
• One Fail2Ban proxy jail located at /etc/fail2ban/jail.d/nginx-proxy.conf and one filter located at /etc/fail2ban/filter.d/nginx-proxy.conf

These default configurations will suffice for this tutorial, but you should feel free to explore and adjust these files to match your own requirements. You can stop all services by running:

sudo supervisorctl stop all

And then, once you are ready, you can restart your services:

sudo supervisorctl start all

Now you are ready to test your installation.

systemctl list-unit-files | grep 'fail2ban\|nginx\|supervisor'

Output
fail2ban.service                       enabled
nginx.service                          enabled
supervisor.service                     enabled

Now that you have properly installed your ERPNext 12 application, you might want to start implementing the system for your business needs. A good starting point is clicking the Getting Started button on the ERPNext Dashboard. ERPNext will then help you configure the platform for all your business and e-commerce needs.

You may also wish to enhance ERPNext’s speed. If that is the case, then you can read ERPNext Performance Tuning, which will guide you through best practices and how to debug performance-related issues.