ERPNext and HRMS with an External MariaDB Database on Ubuntu 24.04 (v16 and v15)

To run ERPNext with an external database, install MariaDB on its own server, set bind-address so it listens on the network, create an admin user with GRANT ALL ... WITH GRANT OPTION for the ERPNext server's IP, open port 3306 only to that server, and then create the site from the ERPNext server with bench new-site yoursite --db-host DB-IP --db-port 3306 --db-root-username youradmin. Install ERPNext and HRMS on the site as usual.

I run ERPNext this way in my homelab: the database lives on its own Proxmox VM (10.11.12.30 in this guide) and the bench server is another VM (10.11.12.31). It lets me snapshot, size and back up the database separately. Replace both IPs with your own.

Quick steps

1. Database server: install MariaDB (11.8 for v16), set utf8mb4 and bind-address = 0.0.0.0.
2. Database server: create frappe_admin@APP-IP with all privileges and grant option; allow 3306 from the app server only.
3. App server: install the ERPNext stack (Python, Node, Redis, bench) without a local MariaDB server, plus mariadb-client.
4. App server: bench init, then bench new-site ... --db-host DB-IP --db-root-username frappe_admin.
5. bench get-app and install-app for ERPNext and HRMS, then bench setup production.

Version note: keep ERPNext and HRMS on the same major version

The first edition of this guide paired ERPNext 15 with HRMS 16. That combination is not supported: Frappe, ERPNext and HRMS must all come from the same branch. This guide uses version 16 throughout; for version 15 swap every version-16 for version-15, use Node 20 and the stock Ubuntu MariaDB 10.11.

Source: Frappe installation docs.

Part 1: Prepare the database server (10.11.12.30)

Install MariaDB

For ERPNext 16, add the official MariaDB 11.8 repository, because Ubuntu 24.04 ships 10.11:

sudo apt update && sudo apt upgrade -y
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash -s -- --mariadb-server-version="mariadb-11.8"
sudo apt update
sudo apt install -y mariadb-server mariadb-client
sudo mariadb-secure-installation

Configure character set and remote access

sudo tee /etc/mysql/mariadb.conf.d/99-frappe.cnf > /dev/null <<'EOF'
[mysqld]
bind-address = 0.0.0.0
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
EOF
sudo systemctl restart mariadb
sudo ss -tlnp | grep 3306

The last command should show MariaDB listening on 0.0.0.0:3306, not 127.0.0.1:3306. If it still shows localhost, another file (often 50-server.cnf) sets bind-address later; change it there too.

Create the admin user for bench

bench needs a user that can create databases and users, so it must have GRANT OPTION. Limit it to the ERPNext server's IP:

sudo mariadb

CREATE USER 'frappe_admin'@'10.11.12.31' IDENTIFIED BY 'UseAStrongPasswordHere';
GRANT ALL PRIVILEGES ON *.* TO 'frappe_admin'@'10.11.12.31' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

Firewall: allow 3306 from the app server only

sudo ufw allow 22/tcp
sudo ufw allow from 10.11.12.31 to any port 3306 proto tcp
sudo ufw enable

Never expose 3306 to the internet. If the servers are in different networks, connect them over a VPN or private network.

Part 2: Prepare the ERPNext server (10.11.12.31)

Install the full ERPNext stack exactly as in my ERPNext 16 on Ubuntu 24.04 guide (frappe user, system packages, wkhtmltopdf, Node 24, Yarn, uv, Python 3.14 and bench), with one difference: skip the MariaDB server step and install only the client libraries:

sudo apt install -y mariadb-client libmariadb-dev

Test the connection before going further:

mariadb -h 10.11.12.30 -P 3306 -u frappe_admin -p -e "SELECT VERSION();"

You should see the server version, for example 11.8.x-MariaDB. If this fails, bench will fail too; jump to troubleshooting below.

Initialise bench and point it at the database server

cd ~
bench init --frappe-branch version-16 frappe-bench
cd frappe-bench
chmod -R o+rx /home/frappe
bench set-mariadb-host 10.11.12.30

bench set-mariadb-host stores db_host in sites/common_site_config.json, so every new site on this bench uses the external server.

Part 3: Create the site and install ERPNext and HRMS

bench new-site erp.example.com \
  --db-host 10.11.12.30 \
  --db-port 3306 \
  --db-root-username frappe_admin \
  --mariadb-user-host-login-scope='10.11.12.31'

Enter the frappe_admin password when asked, then set the Administrator password.

--mariadb-user-host-login-scope sets the host part of the database user bench creates for the site. Without it, bench may create the user for the wrong host and the site cannot connect. Use the app server's IP as above; '%' (any host) also works and is handy if the app server's IP may change, but it is less strict.

Now get and install the apps:

bench get-app --branch version-16 erpnext
bench get-app --branch version-16 hrms
bench --site erp.example.com install-app erpnext
bench --site erp.example.com install-app hrms
bench --site erp.example.com list-apps

Check the site's database settings:

cat sites/erp.example.com/site_config.json

You should see "db_host": "10.11.12.30" (or inherited from common_site_config.json) along with the site's own db_name and db_password.

Part 4: Production setup

bench --site erp.example.com enable-scheduler
bench --site erp.example.com set-maintenance-mode off
sudo env "PATH=$PATH" bench setup production frappe
sudo supervisorctl status

Open http://10.11.12.31 (or your domain) and run the setup wizard. SSL is the same as a single-server install: see step 9 of the main install guide.

Moving an existing site to an external database

1. Take a full backup on the old server: bench --site erp.example.com backup --with-files.
2. Prepare the database server and admin user as in Part 1.
3. On the bench server, point the site at the new host: bench --site erp.example.com set-config db_host 10.11.12.30.
4. Restore the database onto it:

bench --site erp.example.com restore /path/to/xxxx-database.sql.gz \
  --db-root-username frappe_admin \
  --with-public-files /path/to/xxxx-files.tar \
  --with-private-files /path/to/xxxx-private-files.tar
bench --site erp.example.com migrate

Test this on a copy first. My ERPNext backup and restore guide explains each backup file and the encryption key you must carry over.

Troubleshooting external database errors

ERROR 2002 or 2003: Can't connect to MariaDB server on '10.11.12.30'. MariaDB is listening on localhost only or a firewall blocks 3306. Check sudo ss -tlnp | grep 3306 and sudo ufw status on the database server.

ERROR 1130: Host '10.11.12.31' is not allowed to connect. No user exists for that host. Create 'frappe_admin'@'10.11.12.31' as in Part 1. Check with SELECT user, host FROM mysql.user;.

ERROR 1045: Access denied for user '_abc123'@'10.11.12.31' after the site is created. The site's own database user was created for a different host. Recreate the site with --mariadb-user-host-login-scope set to the app server's IP, or on the database server run CREATE USER and GRANT ALL ON \_abc123`.* TO ...for that host using thedb_nameanddb_passwordfromsite_config.json`.

Access denied ... (using password: YES) for frappe_admin. Wrong password or the user lacks GRANT OPTION. Re-run the GRANT ... WITH GRANT OPTION statement.

Slow pages after moving the database. Every page makes many small queries, so latency matters. Keep both servers on the same LAN or VLAN, ideally under 1 ms apart; check with ping 10.11.12.30.

Related guides

• ERPNext installation methods compared, including Docker and Proxmox.
• ERPNext 16 on Ubuntu 24.04, single server.
• Proxmox VE guide for building the two VMs.