ERPNext installation with Docker and bench: a practical guide

Install ERPNext with frappe_docker or bench, create a site, configure workers and scheduler, and understand backups, updates and MariaDB requirements.

ERPNext runs on the Frappe Framework: Python, MariaDB, Redis and a Node-based build step. There are two supported install routes — containers for most people, bench for developers.

Route 1 — Docker (recommended for production)

git clone https://github.com/frappe/frappe_docker
cd frappe_docker
cp example.env .env
# edit .env: DB_PASSWORD, SITES, LETSENCRYPT_EMAIL

docker compose -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > docker-compose.yml

docker compose -f docker-compose.yml up -d

Then create the site inside the backend container:

docker compose exec backend \
  bench new-site erp.example.com \
    --mariadb-root-password "$DB_PASSWORD" \
    --admin-password "$ADMIN_PASSWORD" \
    --install-app erpnext

Route 2 — bench (development)

pip install frappe-bench
bench init --frappe-branch version-15 frappe-bench
cd frappe-bench
bench new-site dev.localhost
bench get-app --branch version-15 erpnext
bench --site dev.localhost install-app erpnext
bench start

MariaDB settings that matter

Frappe requires utf8mb4 with the barracuda file format and large prefixes, otherwise site creation fails with cryptic index errors:

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

Workers, scheduler and queues

Background jobs (emails, stock reposting, scheduled reports) run in RQ workers on short, default and long queues, driven by the scheduler. If invoices submit but stock ledgers never update, the first thing to check is bench doctor and whether the scheduler is enabled:

bench --site erp.example.com doctor
bench --site erp.example.com enable-scheduler
bench --site erp.example.com set-maintenance-mode off

Backups and updates

bench --site <site> backup --with-files produces the SQL dump plus public/private files — you need all three.
Automate off-box copies; the built-in backup only writes to local disk unless you configure S3.
Update with bench update (bench installs) or by pulling a new image tag and running bench migrate (Docker). Always back up first and run on a clone.
Pin your app versions — mixing a v15 site with a v16 image is the most common broken-upgrade cause.

Hardening

Change the Administrator password and create named admin users.
Enable two-factor authentication in System Settings.
Put the site behind HTTPS and restrict /api/method/frappe.client.* exposure with role checks.
Set up fail2ban or rate limiting for the login endpoint.