SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

How to Host ERPNext for VPS with Docker

Set up ERPNext for your own VPS with Docker: eleven containers, sizing, TLS, outbound email, pinned versions, and a restore test wey really work.

Wetin you dey sign up to run

Self-hosting ERPNext for one VPS na operations work, e no be something wey you go fit install with just one command. The official Docker Compose stack get eleven containers, and e dey hold your general ledger and your customer records. This one come increase the standard for everything wey dey below: backup no be backup until you don test am by restoring am, and image tag wey you no pin na schema migration wey fit happen anytime.

Some names dey show for inside this guide. ERPNext na the business application. Frappe na the Python framework wey dey under am. Bench na the command line tool wey dey manage sites, and e don already dey installed inside the containers. One site na one tenant: one MariaDB database plus one directory wey get uploaded files. Almost every command wey dey here dey run bench inside the backend container against one named site.

This guide dey use the frappe_docker repository, wey be the deployment wey the project dey maintain. Every command below was checked against that repository in August 2026. If Docker Compose itself still be new thing for you, running Docker Compose on a VPS cover the ground wey this guide assume say you already sabi.

How much VPS ERPNext need?

ChartERPNext sizing starting points (guidance, not a measurement)
Di data wey dey behind dis chart
[
  {
    "label": "Evaluation",
    "vcpu": 2,
    "ram_gb": 4,
    "disk_gb": 40
  },
  {
    "label": "Small production",
    "vcpu": 4,
    "ram_gb": 8,
    "disk_gb": 100
  },
  {
    "label": "Room to grow",
    "vcpu": 4,
    "ram_gb": 16,
    "disk_gb": 160
  }
]

For evaluation, start with 2 vCPU and 4 GB RAM. Na the evaluation tier be that. These na starting points, no be measurements from this guide, and na the volume of your own documents go decide the real number. The last row no be published minimum at all. E just give you more memory headroom; e no guarantee say memory no go ever finish.

Be honest with yourself about the small plans. 1 GB or 2 GB VPS no leave much headroom for ten containers wey dey run for long, MariaDB buffer pool, plus one Python worker wey dey build report. When memory pressure happen, kernel out of memory killer fit stop one container, and docker inspect for inside am go then show "OOMKilled": true with exit code 137. If dem kill worker in the middle of job, submitted document fit remain with background work wey no finish.

For company wey dey use ERPNext every day, start planning around 8 GB RAM and 4 vCPU with 100 GB SSD, then test your workload. RAM dey finish first. Disk dey grow faster than people expect, because every attachment and every local backup dey land for the same volume wey database dey use.

The eleven containers, and what each one does

Run docker compose ps after the stack don start and ten containers dey run. One more, configurator, go do im work once and exit, na so the total reach eleven.

  • backend dey run the Frappe application under gunicorn. Na here bench dey.
  • frontend na nginx. E dey serve static assets and pass everything else go the backend.
  • queue-short and queue-long na RQ (Redis Queue) workers. Dem dey run background jobs like outgoing email, imports, and report builds.
  • scheduler dey run the time-based jobs, including scheduled reports and auto repeat documents.
  • websocket na the socket.io process behind live updates for the browser.
  • db na MariaDB.
  • redis-cache and redis-queue na two separate Redis instances. One na for cache, and the other na for the job queue.
  • proxy na Traefik, wey the HTTPS override add. E dey own ports 80 and 443, and e dey fetch the certificates.

This split dey important to learn, because e go tell you which log to read. If email hang, na queue worker problem, so docker compose logs -f queue-short na the correct command. If page load but notification badge no ever update, na websocket problem. If you read backend logs for either problem, you go waste the whole afternoon.

Install with production compose files, no be use demo

The repository dey ship pwd.yml, and README talk am clear: "This setup na only for short evaluation. You no go fit install custom apps for this setup." Use am inspect ERPNext for one afternoon. No run company on top am.

sudo apt update && sudo apt install -y git
curl -fsSL https://get.docker.com | bash
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
mkdir -p ~/gitops
cp example.env ~/gitops/erpnext.env

Open ~/gitops/erpnext.env and change four values. ERPNEXT_VERSION pin the image tag. DB_PASSWORD dey ship as 123 for the example file. SITES_RULE na the Traefik routing rule, and LETSENCRYPT_EMAIL provide the ACME account email. Let's Encrypt stop expiration notification emails on June 4, 2025, so monitor certificate expiry separately.

ERPNEXT_VERSION=v16.32.1
DB_PASSWORD=<a long random password>
SITES_RULE=Host(`erp.example.com`)
LETSENCRYPT_EMAIL=ops@example.com

Now render one compose file, then start am.

docker compose --project-name erpnext \
  --env-file ~/gitops/erpnext.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > ~/gitops/erpnext.yaml

docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d
export COMPOSE_FILE="$HOME/gitops/erpnext.yaml"

config no start anything. E merge the base file with the overrides and print the result with every variable already substituted. Then you run that rendered file. This extra step dey useful because the running stack na one file wey you fit read, so e no fit change under you when person edit the env file or when you pull the repository. how several Docker Compose files merge explain the override rules in detail.

The COMPOSE_FILE export make the commands below use the rendered file. Repeat am for every new shell; for cron, pass -f ~/gitops/erpnext.yaml explicitly.

Wait for db to start and for configurator to exit, wey go take few seconds, then create the site.

docker compose --project-name erpnext exec backend \
  bench new-site --mariadb-user-host-login-scope=% \
  --db-root-password '<your DB_PASSWORD>' \
  --install-app erpnext \
  --admin-password '<a strong admin password>' \
  erp.example.com

Check am:

docker compose --project-name erpnext ps
docker compose --project-name erpnext exec backend bench --site erp.example.com list-apps

list-apps suppose print frappe and erpnext with their versions. A healthy ps dey show ten services for running state and none for restarting.

Two things dey often cause problem here. --mariadb-user-host-login-scope=% give the new site's database user wildcard host scope, so e fit still log in when Docker assign the app container another address. Without am, Frappe scope the user to the current connecting host. The app container reach MariaDB through the Docker network, so e arrive as remote host, and database user wey scope to localhost no fit log in from there. This option change the site's database user, no be the root account. The % scope allow connections from any host wey fit reach MariaDB, so keep the database for the private Docker network.

The second one na the site name. By default, the frontend choose which site to serve from the HTTP Host header, so site wey you create as erpnext no go reachable at erp.example.com even though both dey exist. Name the site after the domain, like above, or set FRAPPE_SITE_NAME_HEADER for the env file to the site name and render the compose file again.

HTTPS, and wetin suppose dey true before e work

The compose.https.yaml override dey run Traefik for port 443, redirect port 80 go am, and request certificates from Let's Encrypt. TLS (transport layer security) na wetin stop invoice and session cookie from pass through network as plain text.

Two things suppose dey true, otherwise no certificate go ever issue. DNS A record for erp.example.com must already point to the VPS. Ports 80 and 443 must dey reachable from internet, because Let's Encrypt dey prove say you control the name with HTTP-01 challenge for port 80. Check your provider network firewall, plus the one for the server. Dem na separate controls, and na the panel firewall people dey often forget.

Certificates dey enter cert-data volume for /letsencrypt/acme.json. If browser show default certificate instead of your own, find proxy service name for docker compose --project-name erpnext ps and read its logs for the ACME (automatic certificate management environment) error. You dey run other web apps for the same server? one Traefik instance in front of several Docker Compose apps show how to share the proxy instead of competing for port 443. The second app for server like this often dey face customers, and a self-hosted Chatwoot support desk dey behind that same proxy, so people wey dey handle invoices fit answer customer email and chat for one place.

Email wey dey go out, otherwise invoices no go leave the server

Na this step most ERPNext guides dey skip, and na e dey decide whether the system useful. If outbound mail no dey work, no invoice go reach customer, password reset no go arrive, and scheduled report no go deliver. This stack no contain mail server.

No try send mail direct from VPS through port 25. Providers like AWS dey block outbound port 25 by default, and fresh sending IP wey get small or no history dey increase risk of rejection or spam placement. None of these outcomes must happen. Use authenticated relay for port 587, and first check your provider outbound rules: DigitalOcean dey block ports 25, 465 and 587 for Droplets by default.

The supported way na to use Email Account screen for ERPNext interface, because e stores password encrypted. You fit also write the keys inside site config:

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_server smtp.example.com

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_port 587 --parse

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config use_tls 1 --parse

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config mail_login 'erp@example.com'

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-config auto_email_id 'erp@example.com'

--parse dey store 587 as number instead of string "587". Read the file again and confirm say these two values no get quotes around dem:

docker compose --project-name erpnext exec backend \
  cat sites/erp.example.com/site_config.json

For encrypted password storage, configure outgoing server, login and password together inside Email Account screen. The password field there no set the separate mail_password site config key.

Then send real message. Create Sales Invoice, email am to address wey you control, and monitor the queue as you do am:

docker compose --project-name erpnext logs -f queue-short

Outgoing mail na background job, so if message no arrive, e usually go show as failed job for that log instead of error for browser. Publish SPF (sender policy framework) and DKIM (domainkeys identified mail) records for the sending domain too, then add DMARC policy. Without authentication, invoice wey technically correct fit face rejection or spam placement. If you prefer to control the whole path, self-hosted Mailcow mail server go give you relay wey you control, for separate box from the ERP.

Backups wey actually fit restore

Database dump by itself no be ERPNext backup. Attachments and private files dey inside sites directory, no be MariaDB. If you restore only the database, every uploaded purchase order go come back as broken link.

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

That command go write four files inside sites/erp.example.com/private/backups for sites volume:

  • one -database.sql.gz dump
  • one -files.tar archive of public files
  • one -private-files.tar archive of private files
  • one -site_config_backup.json copy of the site config

The fourth file na the one wey people dey throw away, and na the one wey fit cause serious problem. E hold encryption_key, the key wey Frappe dey use to encrypt stored passwords: email account credentials, payment gateway keys, and every integration secret. If you restore database without the matching key, the site go load normally, but sending mail go fail with:

frappe.exceptions.ValidationError: Encryption key is invalid! Please check site_config.json

Always keep all four files together.

After that, move dem comot from the server. Backup wey dey inside the volume no go survive if the server fail, and bench go prune am anyway: by default, e dey delete backups wey pass 23 hours from that directory. That default na 24 hours before Frappe 16.20.0 and 15.114.0, and the keep_backups_for_hours key for site config fit override am.

docker compose --project-name erpnext cp \
  backend:/home/frappe/frappe-bench/sites/erp.example.com/private/backups \
  ~/erpnext-backups

Run that command from cron, then push the directory go somewhere wey you no dey administer. encrypted restic backups to off-site storage na the correct tool, because e encrypt data before upload, and restic check dey prove say you still fit read the repository. ERP backup na copy of your complete ledger, so keep am encrypted at rest for hardware wey no be this one.

Restore test am before you need am

Backup wey you never test na guesswork. Test am for second site wey dey the same box, never for the live one.

docker compose --project-name erpnext exec backend \
  bench new-site --mariadb-user-host-login-scope=% \
  --db-root-password '<your DB_PASSWORD>' \
  --admin-password '<a strong admin password>' \
  restore-test.example.com

docker compose --project-name erpnext exec backend \
  bench --site restore-test.example.com --force restore \
  sites/erp.example.com/private/backups/<stamp>-erp_example_com-database.sql.gz \
  --with-public-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-files.tar \
  --with-private-files sites/erp.example.com/private/backups/<stamp>-erp_example_com-private-files.tar \
  --db-root-password '<your DB_PASSWORD>'

Copy the encryption key from the backed-up config go the restored site, otherwise its integrations go remain broken:

docker compose --project-name erpnext exec backend \
  bench --site restore-test.example.com set-config encryption_key '<value from site_config_backup.json>'

Now check the restore the way accountant go check am. Open the Accounts Receivable report and compare the closing balance with the live site. Open one recent purchase invoice and download its attachment. Site wey only display login page no prove anything.

Remove the test site when you finish:

docker compose --project-name erpnext exec backend \
  bench drop-site restore-test.example.com

Why version pinning dey matter more for ERPNext

For static site, unpinned image tag mean surprise restart. For ERPNext, e mean schema migration. bench migrate dey rewrite database tables and fit rewrite document data, and e no get undo. To roll back na to restore from backup, no be docker compose down.

So pin the tag. ERPNEXT_VERSION=v16.32.1 na the release wey repository own pwd.yml pin for August 2026. On 2026-11-16, both pwd.yml and example.env pin v16.55.0. No carry any of the two numbers go forward without checking am. Dem list current releases for frappe/erpnext releases page, and image tags wey exist dey for Docker Hub. Read the notes for the version wey you wan move to before you move.

The upgrade itself dey start with backup and maintenance mode.

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com backup --with-files

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-maintenance-mode on

Edit ERPNEXT_VERSION inside ~/gitops/erpnext.env, then render, pull and migrate.

docker compose --project-name erpnext \
  --env-file ~/gitops/erpnext.env \
  -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.https.yaml \
  config > ~/gitops/erpnext.yaml

docker compose --project-name erpnext -f ~/gitops/erpnext.yaml pull
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com migrate

docker compose --project-name erpnext exec backend \
  bench --site erp.example.com set-maintenance-mode off

Maintenance mode dey important because migrate dey alter the schema as e dey run. If user submit document against table wey migration never finish, na so you go end up repairing records by hand.

Move one major version at a time, with backup between each step. Check migration guidance for each major version before you continue.

The repository also ships overrides/compose.migrator.yaml. E add container wey dey run bench --site all migrate on start when sites dey exist and MIGRATE_SITES dey enabled, as e be by default. E convenient. But e also mean say a docker compose up with changed tag fit migrate your production database while nobody dey monitor am. For business system, run migrate as decision wey you make that morning.

Hardening a box wey dey hold customer records

Change the Administrator password for first login. The evaluation compose file dey ship with admin as that password, and people fit carry that habit enter production.

Change DB_PASSWORD comot from the 123 inside example.env. That value go end up as plain text inside the rendered ~/gitops/erpnext.yaml, so chmod 600 the file and no keep am for any git repository. If you want something stronger, overrides/compose.mariadb-secrets.yaml dey read the password from a Docker secret file instead of an environment variable. how to handle env files and secrets for Docker Compose explain the trade-offs.

Publish only the things you need. With the HTTPS override, na ports 80 and 443 dey exposed. No add ports mapping to the db service just to make database client connection easier: that one go put MariaDB for public internet. Use docker compose --project-name erpnext exec backend bench mariadb instead. For the host, allow 22, 80 and 443, deny every other one, and check the provider separate network firewall too.

Turn on two factor authentication for System Settings for every account wey get the System Manager role. That role fit change System Settings, so treat am as administrator account, no be convenience account. If you run several self-hosted apps, Authentik as self-hosted single sign-on provider better pass adding another password for every app.

Patch the host and reboot when kernel updates dey involved. Before you depend on the stack to come back, check the rendered file for restart policy on every service, because stack wey no get one go remain down after that reboot. how to make Docker Compose stack start again after reboot cover the systemd side.

When ERPNext no longer comfortable for one VPS

One VPS fit carry small company for long time. These signs show say e don reach the limit:

  • Background jobs dey pile up, so emails and imports fit arrive minutes or hours late.
  • docker inspect reports containers with "OOMKilled": true or exit code 137.
  • Reports wey take two seconds before now dey take thirty, and MariaDB na the process wey dey hold CPU.
  • Backups dey run long enough for one scheduled run to overlap the next one.

Start by giving MariaDB resources wey e no need share. Database and Python workers dey compete for the same memory, and buffer pool na the part wey need more memory. Bigger application server dey help less than people expect. running the database for Docker or for the host explains that decision, while setting memory limits for Docker Compose prevents one container from starving the others while you dey make the change.

After that, add queue workers instead of web capacity. ERPNext slow work dey happen for background: report generation and bulk imports. More workers need enough CPU and memory headroom. Adding containers to VPS wey already saturated no dey add capacity.

FAQ

How much RAM ERPNext need for VPS?

For evaluation, start with 4 GB and 2 vCPU. For company wey go use am every day, plan for 8 GB and 4 vCPU with 100 GB SSD. When memory pressure dey, kernel out of memory killer fit stop containers, and docker inspect go report am as "OOMKilled": true with exit code 137. These figures na starting points, no be measurements, so monitor your own memory use for the first month.

I fit run pwd.yml for production?

No. The project README talk say na only for short-lived evaluation, and say you no fit install custom apps inside am. Use compose.yaml with the MariaDB, Redis and HTTPS overrides, render dem into one file with docker compose config, then run that file.

Why my ERPNext site no dey reachable immediately after I create am?

By default, frontend choose which site to serve from the HTTP Host header, so the site name must match the domain wey dey for browser. Site wey you create as erpnext no go serve for erp.example.com. Either create the site with the domain as its name, or set FRAPPE_SITE_NAME_HEADER inside the env file to the site name, render the compose file again, then restart the stack.

Wetin must dey inside ERPNext backup?

Four files, and you must keep dem together: the -database.sql.gz dump, the -files.tar and -private-files.tar archives, and the -site_config_backup.json config copy. Running bench --site erp.example.com backup --with-files go produce all four. The config copy hold encryption_key, so if you restore without am, stored integration passwords no go decrypt, and this go show as Encryption key is invalid! Please check site_config.json.

How I fit upgrade ERPNext without spoiling my data?

Back up with --with-files, turn on maintenance mode, change ERPNEXT_VERSION inside your env file, render the compose file again, pull, bring the stack up, then run bench --site erp.example.com migrate and turn off maintenance mode. Move one major version at a time and read the release notes first, because migrate dey rewrite schema and document data without any undo. To roll back, restore the backup wey you take at the beginning.

Dis article help you?