[Guide] How to install ERPNext v14 on Linux Ubuntu (step-by-step instructions)

shashank_shirke · August 6, 2022, 12:30am

Hi guys!

ERPNext v14 has just released and I know everyone wants to try it out quickly. Installing Frappe & ERPNext can be a daunting task, especially when try to install it manually but don’t worry! Just follow this simple step-by-step guide and you’ll sail through the installation process.

This guide might look intimidating at first but trust me it is lengthy because it is detailed and explains each step one by one.

Let’s start!

PRE-REQUISITES:

Operating System: Linux Ubuntu 22.04 LTS
Minimum Recommended Hardware: 2 CPU | 2 GB RAM | 10 GB Disk
Root shell access to the server (via SSH)

SERVER SETUP

1.1 Login to the server as root user

1.2 Setup correct date and timezone (important step as it impacts ERPNext usage)

Check the server’s current timezone

date

Set correct timezone as per your region

timedatectl set-timezone "Asia/Kolkata"

1.3 Update & upgrade server packages

sudo apt-get update -y
sudo apt-get upgrade -y

1.4 Create a new user
We create this user as a security measure to prevent root user access.
This user will be assigned admin permissions and will be used as the main Frappe Bench user

sudo adduser [frappe-user]
usermod -aG sudo [frappe-user]
su [frappe-user] 
cd /home/[frappe-user]/

Note: Replace [frappe-user] with your username. Eg. sudo adduser myname

INSTALL REQUIRED PACKAGES

Frappe Bench and ERPNext requires many packages to run smoothly. In this step we will install all the required packages for the system to work correctly.

Note: During the installation of these packages the server might prompt you to confirm if you want to continue installing the package [Y/n]. Just hit “y” on your keyboard to continue.

2.1 Install GIT

sudo apt-get install git

Check if GIT is correctly installed by running git --version

2.2 Install Python

sudo apt-get install python3-dev python3.10-dev python3-setuptools python3-pip python3-distutils

2.3 Install Python Virtual Environment

sudo apt-get install python3.10-venv

Check if Python is correctly installed by running python3 -V

2.4 Install Software Properties Common (for repository management)

sudo apt-get install software-properties-common

2.5 Install MariaDB (MySQL server)

sudo apt install mariadb-server mariadb-client

Check if MariaDB is correctly installed by running mariadb --version

2.6 Install Redis Server

sudo apt-get install redis-server

2.7 Install other necessary packages (for fonts, PDFs, etc)

sudo apt-get install xvfb libfontconfig wkhtmltopdf
sudo apt-get install libmysqlclient-dev

CONFIGURE MYSQL SERVER

3.1 Setup the server

sudo mysql_secure_installation

During the setup process, the server will prompt you with a few questions as given below. Follow the instructions to continue the setup;

Enter current password for root: (Enter your SSH root user password)
Switch to unix_socket authentication [Y/n]: Y
Change the root password? [Y/n]: Y
It will ask you to set new MySQL root password at this step. This can be different from the SSH root user password.
Remove anonymous users? [Y/n] Y
Disallow root login remotely? [Y/n]: N
This is set as N because we might want to access the database from a remote server for using business analytics software like Metabase / PowerBI / Tableau, etc.
Remove test database and access to it? [Y/n]: Y
Reload privilege tables now? [Y/n]: Y

3.2 Edit the MySQL default config file

sudo vim /etc/mysql/my.cnf

Add the below code block at the bottom of the file;

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

[mysql]
default-character-set = utf8mb4

If you don’t know how to use VIM:

Once the file is open, hit “i” key to start editing the file.
After you’re done editing the file hit “Esc + :wq” to save the file

3.3 Restart the MySQL server (for the config to take effect)

sudo service mysql restart

Instal CURL, Node, NPM and Yarn

4.1 Install CURL

sudo apt install curl

4.2 Install Node

curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash

source ~/.profile

nvm install 16.15.0

4.3 Install NPM

sudo apt-get install npm

4.4 Install Yarn

sudo npm install -g yarn

Check if Node is correctly installed by running node --version

INSTALL FRAPPE BENCH

5.1 Install Frappe Bench

sudo pip3 install frappe-bench

Check if Frappe Bench is correctly installed by running bench --version

5.2 Initialize Frappe Bench

bench init --frappe-branch version-14 frappe-bench

5.3 Go to Frappe Bench directory
This will be the main directory from where we will be running all the commands.
The full path of this directory will be: /home/[frappe-user]/frappe-bench/

cd frappe-bench/

5.4 Change user directory permissions
This will allow execution permission to the home directory of the frappe user we created in step 1.4

chmod -R o+rx /home/[frappe-user]/

5.5 Create a New Site
We will use this as the default site where ERPNext and other apps will be installed.

bench new-site site1.local

Install ERPNext and other Apps

Finally, we’re at the last stage of the installation process!

6.1 Download the necessary apps to our server
Download the payments apps . This app is required during ERPNext installation

bench get-app payments

Download the main ERPNext app

bench get-app --branch version-14 erpnext

Download the HR & Payroll app (optional)

bench get-app hrms

Download the ecommerce integrations apps (optional)

bench get-app ecommerce_integrations --branch main

Check if all the apps are correctly downloaded by running bench version --format table

6.2 Install all the Apps

Install the main ERPNext app

bench --site site1.local install-app erpnext

Install the HR & Payroll app (optional)

bench --site site1.local install-app hrms

Install the ecommerce integrations apps (optional)

bench --site site1.local install-app ecommerce_integrations

SETUP PRODUCTION SERVER

7.1 Enable scheduler service

bench --site site1.local enable-scheduler

7.2 Disable maintenance mode

bench --site site1.local set-maintenance-mode off

7.3 Setup production config

sudo bench setup production [frappe-user]

7.4 Setup NGINX web server

bench setup nginx

7.5 Final server setup

sudo supervisorctl restart all
sudo bench setup production [frappe-user]

When prompted to save new/existing config files, hit “Y”

Ready to Go!

You can now go to your server [IP-address]:80 and you will have a fresh new installation of ERPNext ready to be configured!

If you are facing any issues with the ports, make sure to enable all the necessary ports on your firewall using the below commands;

sudo ufw allow 22,25,143,80,443,3306,3022,8000/tcp
sudo ufw enable

~~Next, I will continue to update this guide to help you setup a custom domain and install SSL certificate.~~

SSL instructions updated in this post

In case you get stuck during any step of this process or have any doubts, feel free to drop your messages below and I’ll try my best to answer.

Thanks,
Shashank

To extend the functionality of ERPNext, if you want to integrate a data analytics software like Metabase, follow this guide:

rtdany10 · August 6, 2022, 3:50am

Well written!

Although I don’t “recommend” this. This is bare minimum.

shashank_shirke · August 6, 2022, 4:25am

Yes it was meant to be minimum recommended hardware. Modified it, thanks.

Manan_Shah · August 6, 2022, 10:16am

Hi Shashank,
Thanks for this. Very detailed guide. Appreciate the effort

For newbies like me, please make a small change in the below instruction,
You need to Hit Esc key and then :wq to save and quit Vim

dineshpanchal432 · August 6, 2022, 10:52am

@shashank_shirke Thank you so much for detailed info.

shashank_shirke · August 6, 2022, 2:28pm

@Manan_Shah Hahaha that’s very humble of you to call yourself a newbie

Thanks for pointing out though, updated it!

Manan_Shah · August 6, 2022, 2:32pm

I am a newbie for these tasks like Installation

On a serious note, this is the easiest installation guide I have come across so far. Thanks

auliabismar · August 6, 2022, 3:18pm

MariaDB refused to start in Ubuntu 22
Please advise

shashank_shirke · August 6, 2022, 4:25pm

Please post the error you’re getting. Also, try rebooting the server once and then check MySQL status by service mysql status

jcagbay · August 7, 2022, 2:33am

Hi! Followed your Ubuntu guide carefully but nothing showed on port 80 web. (Have done similar V14 install on latest Stream and Fedora releases with the same results.)
Here is the error when I bench restart:

$ bench restart
$ supervisorctl restart frappe:
error: <class 'PermissionError'>, [Errno 13] Permission denied: file: /usr/lib/python3/dist-packages/supervisor/xmlrpc.py line: 560
ERROR:
Traceback (most recent call last):
  File "/usr/local/bin/bench", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.10/dist-packages/bench/cli.py", line 127, in cli
    bench_command()
  File "/usr/lib/python3/dist-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.10/dist-packages/bench/commands/utils.py", line 41, in restart
    Bench(".").reload(web, supervisor, systemd)
  File "/usr/local/lib/python3.10/dist-packages/bench/utils/render.py", line 126, in wrapper_fn
    return fn(*args, **kwargs)
  File "/usr/local/lib/python3.10/dist-packages/bench/bench.py", line 150, in reload
    restart_supervisor_processes(bench_path=self.name, web_workers=web)
  File "/usr/local/lib/python3.10/dist-packages/bench/utils/bench.py", line 304, in restart_supervisor_processes
    bench.run(f"{sudo}supervisorctl restart {group}")
  File "/usr/local/lib/python3.10/dist-packages/bench/bench.py", line 47, in run
    return exec_cmd(cmd, cwd=cwd or self.cwd)
  File "/usr/local/lib/python3.10/dist-packages/bench/utils/__init__.py", line 155, in exec_cmd
    raise CommandFailedError
bench.exceptions.CommandFailedError

Usman_Ali · August 7, 2022, 6:24am

try this

shashank_shirke · August 7, 2022, 8:06am

Hi, this looks like a user permission issues. I hope you’re running all the commands as the [frappe-user] with sudo.

If you’re still facing issues, follow this to resolve the problem

jcagbay · August 7, 2022, 11:18am

@shashank_shirke Thank you. That corrected the problem.

CodingRockz · August 7, 2022, 1:13pm

@shashank_shirke - Great guide mate. I think this is probably the first correct guide for version 14 on ubuntu 22.04

I am struggling with installing my positiveSSL on the ERP site, is this something you do as a service?

shashank_shirke · August 8, 2022, 7:50am

Hi @CodingRockz

Good to know that you found the guide helpful. Regarding the SSL certificate issue, you’ll first have to first add a custom domain and then enable dns_multitenant on the default site and then install your SSL certificate on the site.

mwogi · August 8, 2022, 10:59am

@shashank_shirke This is largely a perfect guide thanks. I followed it and the only error that I encountered is on Mariadb barracuda issue.

It is important for the settings to be taken to /etc/mysql/mariadb.conf.d/mariadb.cnf instead of /etc/mysql/my.cnf.

That is the only change I did and it worked.

DrSchnagels · August 8, 2022, 1:34pm

for me the mentioned one in the guide worked.

DrSchnagels · August 8, 2022, 1:45pm

Hello Shashank!
Thank you so much for this guide. Recently I was able to install v13 with my own collected infos, but I never got to work production mode or the correct creation of PDF files.
I used your guide to install a new VM. I have a Proxmox server and I used the LXC Ubuntu 22.04 template.
Everything installed fine and it is much better than my own install guide.
I have one remaining issue: When i create an offer and I want to create&download the offer-PDF-file, then the PDF is zoomed in and the outer edges of the page are missing.
Do you have an idea how to solve this?
Thank you very much for your work!
Edit: It might be this bug:

shashank_shirke · August 8, 2022, 4:25pm

Hi @mwogi

Thanks for the update on this. Some installations might require additional configuration to be done in MariaDB cnf files as well. This was required in v13 but for v14 I tried with just the my.cnf file and it did work.

But I understand some server images and packages repos are different and so might require additional configs. Thanks for updating this.

Also, please do share the exact config you used in the mariadb.cnf file so that it will be helpful for others facing this issue.

shashank_shirke · August 8, 2022, 4:28pm

Hi @DrSchnagels

Great to know that you found the guide useful. As for the PDF generation issue, this has been reported in the past as well.

Can you confirm what version of wkhtmltopdf have you installed by running;

wkhtmltopdf --version

Also, if possible share a screenshot of a sample PDF file that you’re facing issues with.