Installing ERPNext on Debian 10 (Updated for ERPNExt version-13)

ERPNext is an amazing, free and open-source ERP system built using the Frappe-Bench framework. It is scale-able, simple to use and quite beautiful. It is also quite difficult to install outside of the easy-installers which do not play nice in an existing Debian Server setup due to the use of their own, in-house framework called Frappe-Bench.

In my case, I have an LXC Container on Proxmox VE, running Debian 10, MariaDB and Nginx, already serving several apps configured to various subdomains, which means that this existing server is ideally suited to install the ERPNext website on, however this is not as simple, due to the manner in which Bench assumes that it is running alone on the server.

It should be noted that if, like me, you use Proxmox VE with an LXC Container, you will need to enable nested virtualization in the container in order for redis-server to work. Simply edit the Container Config File (/etc/pve/lxc/.conf) and add a line at the bottom: features: nesting=1

In this tutorial, we will work through the steps necessary to implement ERPNext on an existing Debian 10 webserver, I am including the installation of NginX and MariaDB, however if you already have these installed and working, simply adding the necessary changes to your MariaDB instance configuration will be sufficient.

Another important issue is whether you want to run the latest test build of ERPNext or whether you want to use Stable build, note that in order to run the release build (version-13), you MUST ensure that you install the site for ERPNext on a Bench also running the same build (Step 5 and Step 6 have alternate commands to select version-13, you can substitute for any of the current branches found Here).

This how-to assumes that you are logged in as root and have already configured your DNS server to forward the relevant subdomain to the correct server. You don’t need to change your existing Nginx configuration as this setup will install be configured for multi-tenant mode (A separate Nginx instance will be used for ERPNext).

Step 1 – Install Pre-requisite Software Packages:

Install Curl:

apt update && apt install build-essential curl software-properties-common -y

Install Python and pip(Python version 3.6+ and pip version 15+ are required):

apt install python3 python3-setuptools python3-dev python3-pip libffi-dev libssl-dev dirmngr -y

Install virtualenv:
```
apt install virtualenv -y
```
Install Ansible:
```
pip3 install ansible
```
Install gnupg package (In a server system I recommend gnupg1 for its low overhead):
```
apt install gnupg1 -y
```

Install Node.js (version 12+ is required):

curl --silent --location https://deb.nodesource.com/setup_12.x | bash -

apt update && apt install nodejs -y

Install Redis (version 5+ is required) and set to it to start automatically:
```
apt install redis-server -y
```
```
systemctl enable --now redis-server.service
```

Install MariaDB (version 10.3+ is required), you can skip this step if MariaDB is already installed and configured:

apt-key adv --fetch-keys 'https://mariadb.org/mariadb_release_signing_key.asc'

add-apt-repository 'deb [arch=amd64,arm64,ppc64el] https://ftp.osuosl.org/pub/mariadb/repo/10.5/debian buster main'

apt update && apt install mariadb-server libmariadb-dev-compat libmariadb-dev -y

Install yarn (version 1.12+ is required) via npm, it will not work properly if you don’t install via npm:
```
npm install -g yarn
```
Install cron:
```
apt install cron
```

Install wkhtmltopdf (with patched qt):

apt install libxrender1 libxext6 xfonts-75dpi xfonts-base fontconfig -y

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.buster_amd64.deb

dpkg -i wkhtmltox_0.12.6-1.buster_amd64.deb

rm wkhtmltox_0.12.6-1.buster_amd64.deb

Install Nginx, you can skip this step if you already have a working installation of Nginx:
```
apt install nginx -y
```
Install Git:
```
apt install git -y
```
Install Sudo:
```
apt install sudo -y
```

Install Supervisor and set it to start automatically:

apt install supervisor -y

systemctl enable --now supervisor

Step 2 – Configure MariaDB

Configure MariaDB for use with Frappe-Bench:

Edit your mariadb.cnf file to enable the Baracuda engine for innodb:
```
nano /etc/mysql/mariadb.conf.d/50-server.cnf
```

Insert the following below the [mysqld] block:

[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

Edit your clients.cnf file to default the characther set to utf8mb4:
```
nano /etc/mysql/mariadb.conf.d/50-mysql-clients.cnf
```
Insert the following below the [mysql] block:
```
[mysql]
default-character-set = utf8mb4
```
Restart Mariadb
```
systemctl restart mariadb.service
```

Create a MariaDB user with root privileges and a database with the same name as the user for use by Bench, this is necessary as a workaround due to security implementations made to MariaDB which no longer allow root access to non-root Linux users. In this example we use bench, however if you use another name, make sure to substitute it when you create the site in Bench. Also make a note of the password you use in ‘your_password’ as you will need this too:
```
mysql -u root
```
```
CREATE DATABASE bench;
GRANT ALL PRIVILEGES on *.* to bench@localhost identified by 'your_password' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;
```

Step 3 – Create a Linux User to run your Bench

Create a Linux user with sudo priveleges to run your Bench instance:
```
adduser bench
```
- Configure with any password, however make a note in case you need to use it in future.
```
usermod -aG sudo bench
```

Step 4 – Install Bench

Login to Debian with your newly created bench user, or, as root, su to the bench user:
```
su - bench
```
Install Bench:
```
sudo -H pip3 install frappe-bench
```

Step 5 – Create a Bench instance for your ERPNext installation

Create a Bench instance, name it anything you’d like, however I am going to use frappe-bench for ease of reference (by default, bench uses the developer branch, however I will provide either option, note that if you initialize the bench in a specific branch, you MUST also get that version of the ERPNext App, they do not work outside of their brances):
- To install the standard (Developer) branch:
```
bench init frappe-bench
```
- To install the stable (version-13) branch:
```
bench init --frappe-branch version-13 frappe-bench
```
Switch to the newly created Bench instance folder, the name you chose at point 1 above will be the name of the bench folder:
```
cd frappe-bench
```
You can test whether it installed correctly with the following command, which should return the currently installed Bench version, 5.3.0 at the time of updating this how-to:
```
bench --version
```

Step 6 – Download the ERPNExt app for Bench:

If you chose to go with the standard (Developer) branch during step 5:
```
bench get-app erpnext
```
If you chose to go with the stable (version-13) branch during step 5:
```
bench get-app --branch version-13 erpnext
```

Step 7 – Create a site which will host your ERPNext instance:

Note that you should use the fqdn (Fully Qualified Domain Name) which you set up in DNS. For this example we will use erpnext.domain.com. The MariaDB User you created at point 2 in Step 2 can be substituted if you did not use bench as the username for your instance.
Create the Bench site:
```
bench new-site erpnext.domain.com --mariadb-root-username bench
```
- Provide the MariaDB password which you cofigured at point 2 in Step 2 here.
During the installation, the installer will ask you to create an Administrator Password, make a note of the password you choose as you will need it to log in to ERPNext once it is installed.

Step 8 – Install the ERPNext App in your Site

Install the ERPNext Bench App in the Bench Site you created in Step 7 above:
```
bench --site erpnext.domain.com install-app erpnext
```
You can now manually start Bench using the command bench start, however we won’t be doing that as we want it to start automatically, which is done by setting up Bench for Production Use.

Step 7 – Set up Bench for production use

In order to use your ERPNext installation in a production environment, you should automate starting, maintenance and various other tasks, luckily Bench can do this for you by making use of Supervisor, which we installed during Step 1:
```
sudo bench setup production bench
```
- Answer with (y) when asked to replace the default Supervisor and NginX config files.
Enable multi-tenancy for Bench:
```
bench config dns_multitenant on
```
Enable Bench scheduler:
```
bench enable-scheduler
```

And you are done, now simply point your browser at the site you configured: http://erpnext.domain.com/ and it should show you the login page. Use Administrator as the username and the password which you configured during point 3 in Step 7.

Edit – Updating your Bench Sites

When you need to update your Bench sites to the latest version, login as the bench user and cd to your bench instance folder:

cd frappe-bench

bench update

Edit – Updating Frappe Bench

From time to time you might need to update Frappe-Bench, the correct method is to login as the bench user you have created and running the following command:

sudo pip3 install --upgrade frappe-bench

Edit – Restoring from backups

Make sure that you upload the backup files to the /tmp folder, note that there are three (3) files, being …-database.sql.gz which contains the backup of your ERPNext data, …-files.tar which contains your public files and …-private-files.tar which contains your private files. Again, this must be run from your bench folder:

cd frappe-bench

bench --site erpnext.hrcity.co.za --force restore /tmp/...-database.sql.gz --with-private-files /tmp/...-private-files.tar --with-public-files /tmp/...-files.tar --mariadb-root-username bench

Edit – Restart from scratch

If you want to delete all the setup and configuration (Such as when testing) but don’t want to go through all the steps of starting up a new setup, you can simply reset the database as follows:

cd frappe-bench

bench --site erpnext.domain.com --force reinstall --mariadb-root-username=bench

Edit – missing vue.js

You might get an error during update which states that:

UNRESOLVED_IMPORT : 'vue/dist/vue.js' is imported by ../erpnext/erpnext/public/js/hub/marketplace.js, but could not be resolved – treating it as an external dependency
Cannot find some dependencies. You may have to run "bench setup requirements" to install them.
UNRESOLVED_IMPORT : 'vue/dist/vue.js' is imported by ../erpnext/erpnext/public/js/hub/vue-plugins.js, but could not be resolved – treating it as an external dependency
Cannot find some dependencies. You may have to run "bench setup requirements" to install them.
MISSING_GLOBAL_NAME : No name was provided for external module 'vue/dist/vue.js' in output.globals – guessing 'Vue'

It appears that from version-13, vue.js is required, simply install with npm:

npm install vue

and then update your bench:

cd frappe-bench

bench update --reset

Installing ERPNext on Debian 10 (Updated for ERPNExt version-13)

Comments

Leave a Reply Cancel reply