How to Install ERPNext 14 on Debian 11

ERPNext is an open-source Enterprise ERP (Enterprise Resource Planning) system that can be implemented in your business. ERPNext can be implemented in multiple industries, such as manufacturing, distribution, retail, trading, services, education, non-profits, and healthcare. Also, it provides modules like accounting, CRM, sales, purchasing, website, e-commerce, point of sale, manufacturing, warehouse, project management, inventory, and services.

ERPNext is an Enterprise ERP platform licensed under GNU General Public Licence v3. It's mainly written in Python and JavaScript, developed by Frappe Technologies Pvt. ERPNext is an application written under the Frappe framework, an open-source web framework in Python and Javascript.

ERPNext is an alternative to services like NetSuite from Oracle, QAD, Tython, OpenBrave, and Odoo. For functionality, ERPNext is similar to Odoo (formerly OpenERP).

In this tutorial, you will install the ERPNext on a Debian 11 server and then secure the ERPNext with SSL/TLS certificates via Certbot and Letsencrypt. You'll also learn how to install dependencies for ERPNext, such as Python 3.10, Redis, Nginx, Supervisor, Fail2ban, MariaDB Server, Node.js and Yarn, and Frappe Web Framework.

Prerequistes

You will need some following requirements to complete this tutorial:

• One Debian 11 server - This example uses a Debian server with the hostname 'erpnext-server'.
• A non-root user with sudo/root administrator privileges. You will run all commands in this guide as a non-root user.
• A domain name pointed to the server IP address.

Now let's jump to the installation.

Setup New User

The first step in this tutorial is to create a new user that will be used to run the ERPNext application. Also, you will add the new user to the 'sudo' group and allow this user to run commands with root privileges.

Run the below command to create a new user and set up the password for the new user. In this example, you'll create a new user 'frappe' that will be used to run the ERPNext.

sudo useradd -m -s /bin/bash frappe
sudo passwd frappe

Now add the user 'frappe' to the 'sudo' group via the below command.

sudo usermod -aG sudo frappe

Lastly, verify the new user by executing the below command. You'll be logging in as the user 'frappe' and getting the root privileges via the 'sudo su' command.

su - frappe
sudo su

Your terminal prompt should be changed to such as 'root@hostname:/home/frappe..'. Now type 'exit' to log out from the root shell.

With this, you've created a new user for ERPNext. In the next steps, you'll install Python 3.10 manually by compiling it from the source.

Installing Python 3.10

ERPNext is a web application created with a frappeframework, which is based on Python. At the time of this writing, the latest version of the frappeframework and ERPNext required at least Python 3.10.

In this step, you will install Python 3.10 manually from the source. Because the current Debian 11 repository not yet provides the Python 3.10 packages.

Before you get started, ensure that you're logged to your Debian server as the new user 'frappe'.

su - frappe

To start, run the below command to update your Debian package index.

sudo apt update

Now run the below apt command to install dependencies for compiling Python.

sudo apt install wget build-essential libncursesw5-dev libssl-dev \
     libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev libffi-dev zlib1g-dev

Input y when prompted and press ENTER to proceed.

Next, download the Python 3.10 source code from the Python download page via the wget command below. In this example, you'll download and install Python 3.10.9.

wget https://www.python.org/ftp/python/3.10.9/Python-3.10.9.tgz

After the Python source code is downloaded, extract the Python source code via the tar command and move the working directory into it.

tar xzf Python-3.10.9.tgz
cd Python-*/

Now run the below command to compile Python 3.10 and install it.

./configure --enable-optimizations
nproc
sudo make -j2
sudo make altinstall

After the Python installation is finished, you should get your Python binary in the '/usr/local/bin/' directory. Run the below command to verify Python 3.10 installation.

ls /usr/local/bin

You should see the binary file of Python 3.10 packages such as 'python3.10' and 'pip3.10'.

Next, to ensure that you can run the new version of Python commands, you should add the '/usr/local/bin' directory to the system PATH and the visudo secure_path.

Create a new file '/etc/profile.d/custom-path.sh' using the below nano editor command.

sudo nano /etc/profile.d/custom-path.sh

Add the following line to the file.

export PATH=$PATH:/usr/local/bin/

Save the file and exit the editor.

Now run the below command to load the new file '/etc/profile.d/custom-path.sh' and verify the system PATH.

source /etc/profile.d/custom-path.sh
echo $PATH

You should see that the '/usr/local/bin' directory is added to the system PATH environment variable.

Next, run the below command to edit the sudoers configuration.

sudo visudo

On the line 'Defaults secure_path=', add the new binary secure_path '/usr/local/bin'.

Defaults secure_path=....:/usr/local/bin

Save and exit the editor when finished.

With this, you can now execute the new Python 3.10 via the sudo command. Run the below command to verify the Python3.10 and Pip3.10.

sudo python3.10 --version
sudo pip3.10 --version

Below is the similar output you'll receive on your terminal.

Now that you've installed Python 3.10,  move to the next installation of ERPNext dependencies, which is the Nginx web server and Supervisor.

Installing Nginx and Supervisor

To install ERPNext, you must install Nginx which will be used as the default web server, and the Supervisor as the process manager. Both packages the Nginx and Supervisor are available on the Debian repository and you can easily install both packages via APT.

Run the below apt command to install the Nginx and Supervisor packages.

sudo apt install git nginx supervisor

Input y when prompted and press ENTER to proceed.

Next, run the below systemctl command utility to verify both services Nginx and Supervisor. This will ensure that both services Nginx and supervisor is running and enabled, which means both services should run automatically upon the bootup.

Check the Nginx service.

sudo systemctl is-enabled nginx
sudo systemctl status nginx

Output:

Check Supervisor service.

sudo systemctl is-enabled supervisor
sudo systemctl status supervisor

Output:

With the Nginx and Supervisor is installed and running, move to the next installation Redis Server and Fail2ban.

Installing Redis and Fail2ban

Redis is a key-value database that can be used to store temporary data such as sessions. The Fail2ban is a security tool for blocking brute force attacks against your ERPNext applications.

The ERPNext required Redis which will be used as the session manager and the Fail2ban for blocking brute-force attacks on the ERPNext user login page.

Run the below apt command to install Redis and Fail2ban to your Debian server.

sudo apt install redis-server fail2ban

Input y when prompted for the confirmation, then press ENTER to proceed.

After Redis and Fail2ban is installed, run the below systemctl command to verify both services.

sudo systemctl is-enabled redis-server
sudo systemctl status redis-server

sudo systemctl is-enabled fail2ban
sudo systemctl status fail2ban

For the Redis service, you should see the output similar to this - The Redis service is enabled and will be run automatically upon the bootup. And the current status of Redis is running.

For the Fail2ban service, you should see the output similar to this - The Fail2ban service is enabled and will be run automatically upon the bootup. And the current status of Fail2ban is running.

You now have the Redis Server and Fail2ban installed and running. In the next steps, you'll install and configure the MariaDB database server.

Installing and Configuring MariaDB Server

On the default installation, the ERPNext will be using MySQL/MariaDB as the database server. The ERPNext required a specific version of MySQL/MariaDB for the installation.

In this step, you'll install the MariaDB Server 10.6 from the official MariaDB repository. Then, you'll add configurations to your MariaDB Server and secure the MariaDB Server deployment.

Run the below command to add the MariaDB Server repository v10.6.

sudo curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version="mariadb-10.6"

You'll receive an output similar to this.

Now run the below apt command to install the MariaDB packages.

sudo apt install mariadb-server mariadb-client default-libmysqlclient-dev

Input y when prompted for the installation and press ENTER to proceed.

After the MariaDB Server is installed, run the below systemctl command to verify the MariaDB service and ensure that the service is enabled and running.

sudo systemctl is-enabled mariadb
sudo systemctl status mariadb

You should now get the output like the following - the MariaDB service is enabled and will be run automatically upon the bootup. And the current status of the MariaDB service is running.

Next, open the MariaDB Server config file '/etc/alternatives/my.cnf' using the below nano editor command.

sudo nano /etc/alternatives/my.cnf

Add the following lines to the file. The below configuration will enable 'barruca' format on your MariaDB Server and also you'll set up the default character-set for both server and client to 'utf8mb4'.

[mysqld]
innodb-file-format=barracuda
innodb-file-per-table=1
innodb-large-prefix=1
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4

Save the file and exit the editor when finished.

Now run the below systemctl command utility to restart the MariaDB service and apply the changes.

sudo systemctl restart mariadb

Next, you'll then secure your MariaDB deployment.

Run the below command 'mariadb-secure-installation' to secure your MariaDB deployment. You'll then be asked to configure the MariaDB root password, so be sure to input and repeat the new password. For the rest configurations, input Y to confirm and press ENTER.

sudo mariadb-secure-installation

With this, you've now finished the MariaDB Server installation and configuration. In the next step, you will install the wkhtmltopdf package that ERPNext will use for generating PDF reports.

Installing Wkhtmltopdf Package

In this step, you'll install the Wkhtmltopdf package that ERPNext will use to generate PDF reports. The Wkhtmltopdf can be downloaded and installed manually via.deb file or .rpm file. But for Debian, you can install it from the official Debian repository via APT.

Run the below command to install the wkhtmltopdf package. Input Y when prompted and press ENTER to proceed.

sudo apt install xvfb libfontconfig wkhtmltopdf

After Wkhtmltopdf is installed, run the below command to verify it. The wkhtmltopdf command is used to convert the HTML page to PDF, while the wkhtmltoimage is convert the HTML page to various image formats.

which wkhtmltopdf
wkhtmltopdf --version

which wkhtmltoimage
wkhtmltoimage --version

You'll receive the output similar to this - The Wkhtmltopdf v0.12 is installed on your Debian system.

In the next steps, you'll install the Node.js and Yarn package manager that will be used to generate static files for the ERPNext.

Installing Nodejs 16 and Yarn

The latest version of ERPNext is v14, which is required at least the Node.js 16 and Yarn package manager. In this step, you'll install Node.js 16 via the Nodesource repository. Then, install the Yarn package manager.

To begin, run the below command to add the Nodesource repository for Node.js 16.

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash

You'll then receive an output similar to this.

Next, run the below command to add the Yarn repository for the Debian-Linux distribution.

sudo curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

After that, update and refresh your Debian package index via the 'apt update' command. Then, install the Node.js and yarn package manager via the 'apt install' command.

sudo apt update
sudo apt install nodejs yarn

Now the Node.js and Yarn package manager installation should begin.

When the Node.js and yarn is installed, you've now finished the installation of package dependencies for Frappe Web Framework and the ERPNext application.

Installing frappe framework and frappe-bench

ERPNext is an open-source ERP software that was created with frappeframework, which is written in Python and JavaScript. To install ERPNext, you must install the frappeframework on your system, and it's can be installed via the 'frappe-bench' or 'bench'.

So first, you must install the bench. Then, install the frappeframework via the bench. Lastly, you will install the ERPNext application within the frappeframework.

To install the bench, run the below pip3.10 command below.

sudo pip3.10 install frappe-bench

You'll receive an output similar to this during the bench installation.

After the bench is installed, run the below command to verify it. You'll receive the binary path 'bench' command and the current version of the bench you've installed.

which bench
bench --version

With the bench is installed, you will then install the frappeframework. Run the below 'bench' command to install the frappeframework on your current working directory. Also, you'll specify the Python version that will be used to Python 3.10, specify the frappeframework version to v14., and the target installation directory is 'frappe-bench'.

bench init --python python3.10 --frappe-branch version-14 frappe-bench

You'll receive an output similar to this during the frappeframework installation.

After the frappeframework is installed, you should receive the following output at the end of the installation.

Lastly, run the below command to allow other users to read and execute to the frappeframwprk installation directory. This is needed so the Nginx web server can read and execute the frappframework.

sudo chmod -R o+rx /home/frappe/frappe-bench
or
sudo chmod -R o+rx /home/frappe

With frappeframework is installed, you'll then ready to install and set up the ERPNext.

Setup New Site/Project in Frappeframework

Before installing ERPNext, you must create a new site/project on the frappeframework. In this step, you'll create a new site/project and switch the environment into the new project via the bench.

First, move your working directory to 'frappe-bench' via the cd command.

cd ~/frappe-bench

Run the bench command below to create a new site/project for the ERPNext. In this example, you'll create a new site 'erp.howtoforge.local', which is the target domain name of the ERPNext installation. Also, during the setup process, you'll be asked to configure the Administrator password for your frappe project, so input your password and repeat. This password will be used to log in to your ERPNext application.

bench new-site erp.howtoforge.local

Lastly, run the below command to switch to the new site/project 'erp.howtoforge.local'.

bench use erp.howtoforge.local

Below is the output during the site/project creation and after you switched to the new site/project.

Installing ERPNext via frappe-bench

After the new site/project on frappeframework is created, run the below command to download the appt 'payments' and the 'erpnext'. In this example, you'll download the ERPNexxt v14.

bench get-app payments
bench get-app --branch version-14 erpnext

Below is a similar output you'll receive during the 'payments' download process.

And below is the download process of the ERPNext application.

Next, run the below command to install the ERPNext application to the site/project 'erp.howtoforge.local'.

bench --site erp.howtoforge.local install-app erpnext

You'll receive an output similar to this - Also you should see the application 'payments' is automatically installed as the dependency for the ERPNext application.

Lastly, run the bench command below to enable the scheduler and disable the maintenance mode on the site/project 'erp.howtoforge.local'.

bench --site erp.howtoforge.local enable-scheduler
bench --site erp.howtoforge.local set-maintenance-mode off

At this point, the ERPNext installation is finished. But, if you run the ERPNext on production, you should next set up and configure the Nginx web server and Supervisor, which can be configured via bench command.

Deploying ERPNext for Production

First, run the below command to start configuring frappeframeowrk and ERPNext for the production environment. This will install Ansible and set up the ERPNext deployment automatically via Ansible.

sudo bench setup production frappe

Below is the output during the Ansible installation.

Below is the output when the configuration is finished.

Next, run the below bench command to set up Nginx and Supervisor for the ERPNext. When asked to overwrite the current settings, input y to confirm and press ENTER.

sudo bench setup supervisor
sudo bench setup nginx

After that, run the bench command below again to ensure that the Supervisor and Nginx configuration is installed.

sudo bench setup production frappe

Input y to overwrite the current settings and press ENTR to proceed.

Lastly, run the below 'supervisorctl' command with sudo privileges. This will verify all processes and services that is used by frappeframework and ERPNext.

sudo supervisorctl status

If your ERPNext installation is successful, you should receive the output similar to the following - All services for the frappeframework and ERPNext is running.

At this point, you have the ERPNext installation finished and it's running with Nginx as the web server and Supervisor for the process manager. You can now access your ERPNext installation via your domain name and the web browser.

Configuring ERPNext Installation

Open up your web browser and visit the domain name of your ERPNext installation (i.e: http://erp.howtoforge.local/). You'll then see the frappeframework login page.

Input the default user 'Administrator' and input the password that you've used during the process of site/project creation.

Now select the default language, timezone, and currency. Then click Next.

Input the new admin user for your ERPNext installation. Input your full name, email address, and password, then click Next.

Input the company name and upload your company logo, then click Next.

Input details about your organization and click Complete Setup.

You should now see the administration dashboard of your ERPNext installation.

Securing with SSL/TLS Certificates via Certbot and Letsencrypt

In this step, you'll secure the deployment of the ERPNext with SSL/TLS certificates that can be generated using the Certbot tool from Letsencrypt. Before you start, ensure that your domain name is pointed to your server IP address, and ensure that you have an email address that will be used to register to Letsencrypt.

Run the below apt command to install the certbot tool and certbot plugin for the Nginx web server. When prompted, input y to confirm and press ENTER to proceed.

sudo apt install certbot python3-certbot-nginx

After certbot is installed, run the below certbot command to generate SSL certificates for your ERPNext domain name. Be sure to change the domain name and the email address in the below command.

sudo certbot --nginx --agree-tos --no-eff-email --redirect --hsts --staple-ocsp --email [email protected] -d erp.howtoforge.local

With this, the ERPNext installation is now secured with SSL/TLS certificates via Certbot and Letsencrypt. You've also configured the auto-redirect HTTP to HTTPS on your ERPNext domain name, which Certbot automatically handles.

Conclusion

In this tutorial you have learned how to install ERPNext, an open source ERP software, on a Debian 11 server. You also learned how to install some dependencies, such as Python 3.10, which is installed manually by compiling and installing the source code. You installed other dependencies on your Debian server, such as MariaDB, Nginx, Supervisor, Redis and Fail2ban.

You also learned how to install the Frappe framework and build ERPNext on top of it. Then you learned the basic configuration of ERPNext as ERP software.

Finally, you set up ERPNext for production by configuring Nginx as a web server and Supervisor as a process manager. You also secured the use of ERPNext with Certbot and Letsencrypt.