Install and maintain ERPNext v15 on Ubuntu

ERPNext v15 is installed with Frappe Bench, Node.js 20, MariaDB, Redis, Supervisor, Nginx, and the ERPNext, HRMS, Payments, Builder, Education, and Lending apps.

Before you start

• Use a clean, supported Ubuntu server with root or sudo access.
• Point app.example.com to the server before requesting a public TLS certificate.
• Replace every value written as CHANGE_ME and store the generated credentials in a password manager.
• Take a snapshot before changing an existing installation.
• A strong MariaDB root password and ERPNext Administrator password.
• Enough RAM for Redis, workers, MariaDB, and asset builds; use swap only as a safety margin.

What the AppStore installation creates

• Dedicated frappe user and /home/frappe/frappe-bench
• Node.js 20, Yarn, Python tooling, Frappe Bench
• MariaDB, Redis, Supervisor, Nginx, Certbot
• ERPNext, HRMS, Payments, Builder, Education, and Lending

1. Install services and Node.js 20

sudo apt update
sudo apt install -y git curl mariadb-server mariadb-client redis-server \
  supervisor nginx python3-dev python3-pip python3-venv libmysqlclient-dev \
  xvfb fontconfig snapd
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs
sudo npm install -g yarn
sudo snap install --classic certbot
sudo ln -sf /snap/bin/certbot /usr/bin/certbot
sudo systemctl enable --now mariadb redis-server supervisor nginx

2. Create the Frappe user and Bench

sudo useradd -m -s /bin/bash frappe
sudo pip3 install frappe-bench --break-system-packages
sudo -iu frappe
bench init frappe-bench --frappe-branch version-15
exit

3. Create the site and install apps

Run all Bench commands as frappe. Replace the passwords and domain placeholders.

sudo -iu frappe
cd ~/frappe-bench
bench set-config -g redis_queue "redis://127.0.0.1:6379/1"
bench set-config -g redis_cache "redis://127.0.0.1:6379/2"
bench set-config -g redis_socketio "redis://127.0.0.1:6379/3"
bench new-site app.example.com --admin-password 'CHANGE_ME_ADMIN_PASSWORD' --db-root-password 'CHANGE_ME_DB_ROOT_PASSWORD'
bench get-app --branch version-15 erpnext
bench get-app --branch version-15 hrms
bench get-app --branch version-15 payments
bench get-app --branch master builder
bench get-app --branch version-15.2 education
bench get-app --branch version-15 lending
for app in erpnext hrms payments builder education lending; do bench --site app.example.com install-app "$app"; done
bench --site app.example.com enable-scheduler
bench --site app.example.com set-maintenance-mode off
exit

4. Enable production and TLS

cd /home/frappe/frappe-bench
sudo /usr/local/bin/bench setup production frappe
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl restart all
sudo nginx -t
sudo certbot --nginx -d app.example.com -m [email protected] --agree-tos --redirect

Important files and data

• Bench: /home/frappe/frappe-bench
• Site data/config: /home/frappe/frappe-bench/sites/app.example.com
• Apps: /home/frappe/frappe-bench/apps
• Supervisor and Nginx configs generated by Bench

Health checks and logs

Run these checks after installation and after each upgrade:

sudo -iu frappe bash -lc 'cd ~/frappe-bench && bench --site app.example.com list-apps && bench doctor && bench version'
sudo supervisorctl status
sudo nginx -t
sudo systemctl status mariadb redis-server supervisor nginx --no-pager

Routine maintenance

Review release notes and take a backup or snapshot before upgrading. Use the following playbook-aligned commands as the starting point:

sudo -iu frappe
cd ~/frappe-bench
bench --site app.example.com set-maintenance-mode on
bench update --reset
bench --site app.example.com migrate
bench build
bench restart
bench --site app.example.com set-maintenance-mode off

Backup scope

• bench --site app.example.com backup --with-files output copied off-server
• The complete site directory, custom apps, and exact app branches/commits
• MariaDB/Redis/Nginx/Supervisor configuration needed to reproduce the host

A usable backup needs both application files and application data. Test restoration on a separate server; an untested backup is not a recovery plan.

Troubleshooting

• Confirm DNS with dig +short app.example.com before retrying Certbot.
• Test the web-server configuration before reloading it: sudo nginx -t or sudo apache2ctl configtest.
• Check free space with df -h and listening ports with sudo ss -ltnup.
• If a service fails, inspect its systemd journal before changing configuration.
• Run Bench commands as frappe with the system-installed Bench command in PATH.
• If an app branch is missing or incompatible, stop and select a release combination validated for ERPNext v15 instead of forcing migration.

Security notes

• Do not paste passwords, API keys, repository credentials, private keys, or access tokens into tickets or public logs.
• Expose only the documented public ports. Keep database and application backend ports bound to localhost or a private network.
• Keep SSH access working before enabling UFW, then allow only the ports this guide lists.
• Renewal can be tested safely with sudo certbot renew --dry-run where Certbot manages TLS.