I love Archlinux and ERPNext. When it came to installing ERPNext, most of available resources on Internet deal with Ubuntu or containerized installation.
Truth be told, I could find a guide for Archlinux but it turned out to be inaccurate and outdated.
After days of researches and try/fails, I got ERPNext to work on Archlinux and here I am sharing my experience.
A. Objective
The aim of this guide is to get ERPNext up and running, on an Archlinux server.
B. Requirements
An Archlinux server with root access and internet connection are required. Assumptions are made here that the user is familiar with Linux environment and culture. The user should be able, among other things, to navigate the Linux filesystem, edit text files and append text to files …
Think security. If your server is exposed to a public network, it’s not a good practice to ssh to it as root, even with strong public/private key authentication. You may rather create a standard account to use to ssh to your server. In this case you may need to add the created account to sudoers and prefix your commands with sudo.
C. Getting help
Installing and dealing with Archlinux may be a challenge even for confirmed Linux users coming from other distributions like Debian/Ubuntu or Fedora, but from my personal experience, installing Archlinux is easier and more straightforward than many famous distributions and it has a solid asset for that: ArchWiki. The secret to get things done is to RTFM which stands for “Read the F* Manual” (any average Archlinux user would not agree that the F is for Field).
So please RTFM before asking for help.
D. Convention
Commands prefixed with # are meant to be run as root (or prefixed with sudo otherwise) while commands prefixed with $ are meant to be run as a non-root user.
Some tools are not mandatory and the user can use similar ones to achieve similar results. Example: nano is used in this guide but any other text editor can do.
E. Main steps
- Install Archlinux
- Add a new user
- Install required packages
- Configure database
- Install Bench CLI
- Configure Supervisor
- Create a Bench
- Get ERPNext and other apps
- Create Site
- Install apps to our site
- Test development server
- Supervisor setup
- Nginx setup
- wkhtmltopdf install
- Fonts setup
- Layout correction
F. Getting Archlinux ready
01.Install Archlinux
A fresh Archlinux install is recommended. Make sure it is connected to Internet before continuing.
02.Add a new user.
For strong security reasons, it is not recommended to use root user to run ERPNext. We will create a standard user, let’s call him archer, for this purpose:
Create a new user:
# useradd -m archer
Protect the new user account with a super strong password:
# passwd archer
03.Install required packages.
Install the following packages using pacman:
# pacman -Syu
# pacman -S mariadb redis python-pip git gcc npm nginx openssl nano supervisor cronie which openssl-1.1
# npm install -g yarn
04.Configure database.
We will configure MariaDB, a flavor of MySQL preferred by Archlinux, to use with ERPNext.
Run the following commands to configure MariaDB:
# mysql_install_db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
# systemctl enable mariadb --now
# mysql_secure_installation
The last command will ask some questions. In case of doubt, follow the suggested default answers. In my case, I answered Yes to all except for “Remote login” which I don’t need, so I answered No.
Make sure to choose a super strong password for the database and remember it.
Now, make the following changes to MySQL configuration file:
# nano /etc/my.cnf
Append the following lines to the file:
[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
Finally, enable redis service and restart mariadb:
# systemctl enable redis --now
# systemctl restart mariadb
G. Frappe Bench configuration
05.Install Bench CLI
Login as archer and use python-pip to install the Bench CLI (Command Line Interface):
$ pip install frappe-bench
Now add /home/archer/.local/bin to system path in order to avoid “command not found” error. To do this permanently, edit /etc/profile as follows:
# nano /etc/profile
…
# Append our default paths
append_path …
append_path ‘/home/archer/.local/bin’
…
You may need to log out and log in for those changes to take effect.
To make sure the bench CLI was correctly installed, issue the following command as archer. It should output the installed version of bench:
$ bench --version
5.16.0
06.Configure Supervisor
Login as root (or use sudo before every command if you added archer to sudoers) and enable supervisord.service:
# systemctl enable supervisord --now
To avoid “/etc/supervisord.conf not found error”, change its mode to 644:
# chmod 644 /etc/supervisord.conf
To be able to use supervisorctl and bench commands without elevated privileges, make the following changes under /etc/supervisord.conf:
# nano /etc/supervisord.conf
Edit the following lines:
…
[unix_http_server]
file=/var/run/supervisor.sock ; the path to the socket file
chmod=0700 ; socket file mode (default 0700)
chown=archer:archer ; socket file uid:gid owner
…
[supervisorctl]
serverurl=unix:///var/run/supervisor.sock ; use a unix:// URL for a unix socket
;serverurl=http://127.0.0.1:9001 ; use an http:// url to specify an inet socket
…
Save the changes and restart the supervisord service:
# systemctl restart supervisord
As archer, reread the configuration file and reload the supervisorctl:
$ supervisorctl reread
$ supervisorctl reload
H. Bench, Site and Apps
We will create our first bench, let’s name it bencher, and download ERPNext application (and optionally other applications) to it. Then we will create a site, akham.ino, and install applications to it.07.Create a Bench
As archer, run the following command from archer’s home directory:
$ bench init bencher
Be patient, it may take some time. If at this stage you get an error like “supervisor restarting failed” just ignore it for now, we’ll take care of it later.
08.Get ERPNext and other apps
Move to bencher folder and use bench CLI to download apps. Let’s download erpnext and hrms apps
$ cd bencher
$ bench get-app erpnext
$ bench get-app hrms
If at this stage you get an error like “supervisor restarting failed” just ignore it for now, we’ll take care of it later.
09.Create Site
$ bench new-site akham.ino
It will ask for the password we setup in database configuration step.
You also will be prompted to setup a password for the Administrator user of the site. You will need this password to login to your site.
You may get a warning that MariaDB is newer than what is supported. Ignore it, it’s just Archlinux being ahead of time as usual.
Let’s set our site as default site by running:
$ bench use akham.ino
Thus, we may issue commands to bench without specifying “-- site akham.ino” at each time.
10.Install apps to our site
Let’s install ERPNext and any apps we previously got:
$ bench --site akham.ino install-app erpnext
$ bench --site akham.ino install-app hrms
11.Test development server
Congratulations. You can now test the installation by running a development server:
$ bench start
This will launch a development server. You can test it by going to a browser and point to: http//:[ArchlinuxServer-IP-address-or-Hostname]:8000. In my example: http//:192.168.10.14:8000
To stop the server, press Control+C on the terminal.
Till now, we have ERPNext up and running as a development server. If you want only to test and or develop apps, this can be enough. However, it’s not suitable for production.
I. Production setup
For a production environment, we need to setup nginx and supervisor for our site. Then we will setup wkhtmltopdf in order to let our end users generate beautiful pdf reports.
12.Supervisor setup
Inside the bencher directory, run the following command as archer:
$ bench --site akham.ino setup supervisor
If succeeded, this command will generate the following file: /home/archer/bencher/config/supervisor.conf
In order to make it effective, we need to append it to /etc/supervisord.conf by running (as root):
# cat /home/archer/bencher/config/supervisor.conf >> /etc/supervisord.conf
Let’s run (as archer) the following commands to take the new changes into account:
$ supervisorctl reread
$ supervisorctl reload
13.Nginx setup
$ bench --site akham.ino setup nginx
If succeeded, this command will generate the following file: /home/archer/bencher/config/nginx.conf
In order to make it effective, we need to include it in /etc/nginx/nginx.conf by running (as root):
# nano /etc/nginx/nginx.conf
And adding an include statement inside http { } block. We need also to remove or comment out everything inside the server block listening at 80.
…
http {
…
# server {
# listen 80;
# server_name localhost;
#…
#}
…
include /home/archer/bencher/config/nginx.conf;
}
…
Nginx will fail at this stage because of a syntax on the generated configuration file at /home/archer/bencher/config/nginx.conf. We should comment out a “main” keyword in the file, like the following:
$ nano /home/archer/bencher/config/nginx.conf
…
http {
…
# server {
…
access_log /var/log/nginx/access.log; #main;
error_log /var/log/nginx/error.log;
…
14.wkhtmltopdf install
The last version of wkhtmltopdf is not working fine with ERPNext as per my experience. We’ll need to install wkhtmltopdf 0.12.6 (with patched qt) from the link “https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-3/wkhtmltox-0.12.6-3.archlinux-x86_64.pkg.tar.xz”. We can do this in Archlinux server by using wget command:
# pacman -S wget
# cd /tmp
# wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-3/wkhtmltox-0.12.6-3.archlinux-x86_64.pkg.tar.xz
# pacman -U wkhtmltox-0.12.6-3.archlinux-x86_64.pkg.tar.xz
Without “which” installed, we may get an error when trying to generate a pdf saying it did not find wkhtmltopdf. If wkhtmltopdf was correctly installed, the command “wkhtmltopdf --version” should output “wkhtmltopdf 0.12.6 (with patched qt)”
$ wkhtmltopdf –version
wkhtmltopdf 0.12.6 (with patched qt)
15.Fonts setup
At this stage, any pdf we generate is only dark blocks because it misses fonts. Let’s use the fonts from github.com/frappe/fonts. The method is explained there.
16.Layout correction
Finally let’s restart the Archlinux server.
As archer, let’s build production assets:
$ bench build
$ bench clear-cache
$ bench restart
Our site is up and running, accessible at our Archlinux server address.
Let’s visit it on a web browser. “http//:192.168.10.14” (without the port number :80, thanks to nginx).
The site should be available after the server starts up, without any need to login.
If you get an ugly layout on the login page, it is probably due to a permission issue that we may correct by running :
# chmod o+x /home/archer
