Knowledgebase

Last Updated: 31 August 2025
Applies to: Ubuntu 24.04 LTS (fresh server recommended)
Skill Level: Intermediate to Advanced

Overview

This guide shows how to manually install ERPNext 14 on Ubuntu 24.04 in production mode using Bench, NGINX, Supervisor, MariaDB, and Let's Encrypt SSL.

Prerequisites

Before starting, ensure you have:

• Ubuntu 24.04 VPS with root (or sudo) access
• A domain pointing to your VPS (A record)
• The following values ready:

Step 1: Clear APT Locks and Stop Unattended Upgrades

sudo fuser -k /var/lib/dpkg/lock-frontend || true
sudo rm -f /var/lib/dpkg/lock-frontend /var/lib/dpkg/lock
sudo dpkg --configure -a || true

sudo systemctl stop unattended-upgrades
sudo systemctl disable unattended-upgrades
sudo systemctl mask unattended-upgrades

Step 2: Create the frappe User

sudo adduser frappe
sudo usermod -aG sudo frappe
echo "frappe:FRAPPE_PASSWORD" | sudo chpasswd

Replace FRAPPE_PASSWORD with your chosen password.

Step 3: Install System Dependencies

sudo apt update
sudo apt install -y \
software-properties-common dirmngr ca-certificates apt-transport-https \
curl snapd python3-dev python3-pip python3-venv python3-pymysql \
git redis-server xvfb libfontconfig wkhtmltopdf libmysqlclient-dev gnupg2 \
fontconfig libjpeg-turbo8 xfonts-75dpi mariadb-server mariadb-client nginx \
libxrender1 libxext6 libssl-dev build-essential locales

Step 4: Start and Secure MariaDB

sudo systemctl enable mariadb
sudo systemctl start mariadb

Secure root user and remove insecure defaults:

sudo mysql -u root <<EOF
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'DB_ROOT_PASSWORD';
DELETE FROM mysql.user WHERE User='';
DROP DATABASE IF EXISTS test;
DELETE FROM mysql.db WHERE Db='test' OR Db='test\\_%';
DELETE FROM mysql.user WHERE User='root' AND Host='%';
FLUSH PRIVILEGES;
EOF

Replace DB_ROOT_PASSWORD.

Optional convenience file for root:

sudo tee /root/.my.cnf > /dev/null <<EOL
[client]
user=root
password=DB_ROOT_PASSWORD
EOL
sudo chmod 600 /root/.my.cnf

UTF-8 MB4 settings:

sudo tee -a /etc/mysql/my.cnf > /dev/null <<EOL
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
EOL
sudo systemctl restart mysql

Step 5: Install Node.js 18 and Yarn

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
sudo npm install -g yarn

Step 6: Install Certbot

sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Step 7: Clean Up APT

sudo apt autoclean -y
sudo apt autoremove -y

Step 8: Install Bench CLI

sudo pip3 install frappe-bench

Step 9: Initialize Bench and Create Site

Switch to the frappe user:

sudo su - frappe

Initialize bench with your chosen branch (version-14):

bench init --frappe-branch VERSION bench

Create your ERPNext site:

cd ~/bench
bench new-site SITE_NAME --admin-password ADMIN_PASSWORD --db-root-password DB_ROOT_PASSWORD

Fetch ERPNext app and install it:

bench get-app --branch VERSION erpnext
bench --site SITE_NAME install-app erpnext
bench --site SITE_NAME enable-scheduler
bench --site SITE_NAME set-maintenance-mode off

Replace VERSION (e.g., version-14), SITE_NAME, ADMIN_PASSWORD, DB_ROOT_PASSWORD.

Step 10: Setup Production with NGINX and Supervisor

Still as the frappe user:

cd ~/bench
bench setup production frappe

Step 11: Obtain SSL Certificate

Issue a certificate for your domain (runs system-wide, not as the frappe user):

exit
sudo certbot --nginx -d SITE_NAME --non-interactive --agree-tos -m admin@SITE_NAME

Optional: add hardened SSL params referenced by NGINX (if needed by your setup):

sudo tee /etc/nginx/snippets/ssl-params.conf > /dev/null <<EOL
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM";
ssl_ecdh_curve secp384r1;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8;
EOL
sudo systemctl reload nginx

Step 12: Verify Supervisor and NGINX

sudo systemctl restart nginx
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart all
sudo supervisorctl status

Login to ERPNext

Open in your browser:

https://SITE_NAME

• Username: Administrator
• Password: ADMIN_PASSWORD

Troubleshooting

• Check site logs

sudo su - frappe
cd ~/bench
bench --site SITE_NAME logs

• Restart all processes

sudo supervisorctl restart all

Notes

• Use a fresh VPS to avoid port and package conflicts.
• Keep all passwords secure and rotate regularly.
• To update later: bench update (review release notes first).