How to Install ERPNext 15 on Ubuntu 22.04: A Step-by-Step Guide [Update 2025]

This guide provides a comprehensive walkthrough of installing ERPNext version 15 on an Ubuntu 22.04 server. We’ll cover everything from setting up your server to configuring ERPNext for production use.

Prerequisites

To ensure a smooth installation, make sure you have the following:

• Software:
  • Ubuntu 22.04 server (updated)
  • A user account with sudo privileges
  • Python 3.10 or higher
  • Node.js 18
• Hardware:
  • At least 4GB of RAM
  • 40GB of hard disk space

Server Setup

Update and Upgrade Packages

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

Create a new user – (bench user)

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

Install Required Packages

sudo apt-get install git python3-dev python3.10-dev python3-setuptools python3-pip python3-distutils python3.10-venv software-properties-common mariadb-server mariadb-client redis-server xvfb libfontconfig wkhtmltopdf libmysqlclient-dev1 curl

Configure MariaDB

sudo mysql_secure_installation

When you run this command, the server will show the following prompts. Please follow the steps as shown below to complete the setup correctly.

Reload privilege tables now? [Y/n]: Y

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

Edit MySQL default config file

sudo nano /etc/mysql/my.cnf

Add the following block of code exactly as is:

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

[mysql]
default-character-set = utf8mb4

Restart MariaDB:

sudo service mysql restart

Restart MariaDB:

Install Node.js, NPM, and Yarn

sudo apt install curl
curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash
source ~/.profile
nvm install 18
sudo apt-get install npm
sudo npm install -g yarn

Install and Initialize Frappe Bench

sudo pip3 install frappe-bench
bench init --frappe-branch version-15 frappe-bench
cd frappe-bench
chmod -R o+rx /home/[your-erpnext-user]

Create a New Site

bench new-site [your-site-name]

Install ERPNext and Other Apps

bench get-app payments
bench get-app --branch version-15 erpnext
bench --site [your-site-name] install-app erpnext
bench --site [your-site-name] install-app payments 

Start the Server

bench start

Access your ERPNext instance at [YOUR SERVER IP]:8000.

Set up for Production

bench --site [your-site-name] enable-scheduler
bench --site [your-site-name] set-maintenance-mode off
sudo bench setup production [your-erpnext-user]
bench setup nginx
sudo supervisorctl restart all
sudo bench setup production [your-erpnext-user]

Your ERPNext instance should now be accessible at your server’s IP address without the port number.

Troubleshooting

I encountered an issue with the Redis port number mismatch.

Please look into these 2 files and match the default port number of redis which is 6379

cat /home/frappe/frappe-bench/sites/centaq/site_config.json
cat /home/frappe/frappe-bench/sites/common_site_config.json

Change the Redis port:

• Locate the lines with "redis_cache" and "redis_socketio".
• Change the port number from 13000 to 6379 in both lines.
• The corrected lines should look like this: JSON"redis_cache": "redis://127.0.0.1:6379", "redis_socketio": "redis://127.0.0.1:6379",

Conclusion

Congratulations! You have successfully installed ERPNext 15 on your Ubuntu 22.04 server. Remember to consult the official ERPNext documentation for further customization and troubleshooting.