Deploying ERPNext 13 on Ubuntu 20.04 LTS (Focal Fossa)

• ERPNext
• erp
• odoo
• 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 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.

This tutorial will show you how to deploy ERPNext 13 on a Scaleway machine running Ubuntu Focal Fossa (20.04 LTS). This could be a Dedibox, an Instance or an Elastic Metal server.

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
• One of the following remote machines running Ubuntu Focal Fossa (20.04 LTS):
  • An Instance
  • An Elastic Metal server
  • A Dedibox dedicated server
• 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.

1. 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.

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

   apt update && apt upgrade -y
   

3. 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.

   adduser mariecurie
   

4. Give the new user sudo privileges:

   usermod -aG sudo mariecurie
   

5. Configure the locale of the system to en_US.utf8:

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

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

   nano /etc/environment
   

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

   Save the file, exit the text editor

7. Reboot your instance using the reboot command.

8. Wait a minute for the reboot to finish, then SSH back into your instance with the following command:

   ssh root@<remote_machine_ip>
   

9. Switch to the mariecurie user.

   su - mariecurie
   

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

Installing MariaDB

1. Add a MariaDB mirror to the apt configuration. 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://archive.mariadb.org/repo/10.6/ubuntu focal main'
   sudo apt update
   

2. Install MariaDB using the apt package manager:

   sudo apt install mariadb-server-10.6 mariadb-client-10.6
   

3. Install the following packages which are required for ERPNext:

   sudo apt install libmysqlclient-dev python3-mysqldb
   

4. Run the interactive setup tool to finalize the installation of MariaDB:

   sudo mysql_secure_installation
   

   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.

5. Log in to the MySQL shell. We use a non-root user with superuser privileges:

   sudo mysql
   

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

   CREATE DATABASE mariecurie;
   

7. Create the 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 'mariecurie'@'%' IDENTIFIED BY 'strong_database_password' WITH GRANT OPTION;
   

8. Flush the privileges to activate the new user account:

   FLUSH PRIVILEGES;
   

9. Exit the MariaDB shell:

   EXIT;
   

10. Open the file /etc/mysql/conf.d/50-server.cnf in 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:

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

11. Repeat step 10 for the file /etc/mysql/my.cnf:

    sudo nano /etc/mysql/my.cnf
    

12. Restart the MariaDB server:

    sudo service mysql restart
    

Setting up ERPNext

Installing prerequisites

1. 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 python3-testresources
   

2. Continue to install the required python dependencies and upgrade pip

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

3. 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
   

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

   sudo bash nodesource_setup.sh
   

5. Install NodeSource using apt:

   sudo apt install nodejs
   

6. Install yarn using npm:

   sudo npm install -g yarn
   

7. Download the wkhtmltopdf package in the /tmp directory. ERPNext uses wkhtmltopdf to 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
   

8. Install the downloaded package using dpkg:

   sudo dpkg -i wkhtmltox_0.12.6-1.focal_amd64.deb
   

9. Copy all the relevant binary files from the installation to the /usr/bin directory:

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

10. Make those files executable:

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

11. Return to the /home directory of the user:

    cd /home/mariecurie
    

Installing Redis

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

1. Install Redis using the apt package manager:

   sudo apt install redis-server
   

2. 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.

1. Clone the bench GitHub repository using git:

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

2. Install the bench CLI using pip3:

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

Installing the Frappe framework

1. 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
   

2. Initialize the Frappe framework using the following command. Remember to replace /home/mariecurie with 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 directory and x is not a valid editable requirement.

   Tip

   The Frappe framework requires specific versions of certain Python packages. In case the bench init command fails, install the versions required by running the following command:

   sudo pip3 install markupsafe==2.0.1 setuptools==40.8.0 ansible==5.3.0 ansbile-core==2.12.2 jinja2==2.10.3
   

   Once the installation completes, you 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
   

Installing ERPNext web application

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

   cd /home/mariecurie/frappe-bench
   

2. Download ERPNext using the bench command-line interface:

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

3. Run the following command to install any missing dependencies:

   bench setup requirements
   

4. 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:

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

5. 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
   

6. 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 IP’s 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.

1. Run bench with the following parameters. Replace mariecurie with the name of your user owning the production environment if necessary. Ensure you execute the command from the frappe-bench directory of your user.

   sudo bench setup production mariecurie
   

   It will create 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. Install certbot using 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
   ```  ```
   

3. 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

1. Open a web browser on your local computer and point it to https://your_erpnext_domain/. The login page displays. Enter the username 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.

2. Choose your language, then click Next:

   

3. Set your country, timezone, and currency, then click Next:

   

4. 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:

   

5. 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:

   

6. 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:

   

7. 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.

   

Going further

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.