Installing ERPNext on Fedora 37

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 Fedora 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 Fedora 37, 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 Fedora 37 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-14), 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-14, 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:

Let’s work from a fully up-to-date server by updating packages:
```
dnf update
```

Install the pre-requisite packages:

dnf install mariadb mariadb-server mariadb-devel python-setuptools nginx zlib-devel bzip2-devel openssl-devel postfix python-devel python-pip libxml2 libxml2-devel libxslt libxslt-devel redis libXrender libXext supervisor cronie which xorg-x11-fonts-75dpi xorg-x11-fonts-Type1 libjpeg-devel redhat-rpm-config python-crypto nodejs npm git nano

Install Yarn:
```
npm install -g yarn
```
Enable the Redis server to automatically start:
```
systemctl enable --now redis.service
```
Enable the NginX server to automatically start:
```
systemctl enable --now nginx.service
```
Enable the MariaDB server to automatically start:
```
systemctl enable --now mariadb.service
```
Enable Supervisor to automatically start:
```
systemctl enable --now supervisord
```

Step 2 – Configure MariaDB

Run the MariaDB secure installation wizard (Skip if already configured):Insert the following below the [mysqld] block:
```
mysql_secure_installation
```

Make the following selections, remembering to make a note of your root Password:

Enter current password for root (enter for none): (Press Enter)
Set root password? [Y/n] Y
New password: 
Re-enter new password: 
Remove anonymous users? [Y/n] Y
Disallow root login remotely? [Y/n] Y
Remove test database and access to it? [Y/n] Y
Reload privilege tables now? [Y/n] Y

Edit the mysql server file:
```
nano /etc/my.cf
```

And insert the following blocks at the end of 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

Now restart the MariaDB server for the changes to take effect:
```
systectl restart mariadb.service
```

Step 3 – Install frappe-bench (Do this as root still):

```
pip install frappe-bench
```

Step 4 – Create a bench user with sudo priveleages:

Create a user:
```
adduser frappe
```
Set a password for the new user (Make a note of this password):
```
passwd frappe
```
Add the newly created user to the wheel group for sudo access:
```
gpasswd wheel -a frappe
```

Step 5 – Create a Bench instance for your ERPNext installation

Switch to the new user you created as you will be doing most of the rest of the configuration from here:
```
su frappe
```
Switch to the frappe user’s home folder:
```
cd
```
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 branches):
- To install the standard (Developer) branch:
```
bench init frappe-bench
```
- To install the stable (version-14) branch:
```
bench init --frappe-branch version-14 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
```
Make the newly created bench folder executable (This is important):
```
chmod -R o+rx /home/frappe/
```
You can test whether it installed correctly with the following command, which should return the currently installed Bench version, 5.16.2 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-14 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.
Create the Bench site:
```
bench new-site erpnext.domain.com
```
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 9 – 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, while frappe-bench uses Supervisor to automate this, as well as loading the WSGI server, it doesn’t want to play nicely with Fedora, so I devised the following work-arounds:

Turn off maintenance mode in the bench:

bench --site erpnext.domain.com set-maintenance-mode off

Enable scheduler:

bench --site erpnext.domain.com enable-scheduler

Generate an NginX Config File:
```
bench setup nginx
```
Generate a Supervisor Config File:
```
bench setup supervisor
```

And now for the work-arounds, ordinarily, sudo bench setup production would have taken care of most of this, however due to multi-tenancy on a preconfigured server and some funniness with how Fedora treats Python Scripts between Virtual Environments and the OS, we will be manually configuring Supervisor and NGinX. Luckily, the above bench setup commands generated the conf files we need, however depending on your virtual-host configuration of NginX, you might want to change it around.

Create a symlink for NginX in your NginX conf directory:

sudo ln -s ./config/nginx.conf /etc/nginx/conf.d/erpnext.domain.com.conf

Create a symlink for Supervisor in your Supervisor conf directory:

sudo ln -s ./config/supervisor.conf /etc/supervisord.d/erpnext.ini

Reload NginX:
```
sudo systemctl reload nginx.service
```
Now exit the session of your bench user and revert to root user:
```
exit
```
As root user, have Supervisor read the new config file:
```
supervisorctl reread
```
Update Supervisor Configuration:
```
supervisorctl update
```
And now start the erpnext configuration in Supervisor:
```
supervisorctl restart erpnext
```

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.

Step 10 – Install Additional Modules

Following some changes to version 14, need to install HR / Payroll module:

bench get-app hrms

bench --site erpnext.domain.com install-app hrms

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 pip 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 Fedora 37

Comments

Leave a Reply Cancel reply