VPS Tutorials
ERPNext on a VPS: Frappe Docker, HTTPS, queues and recovery
Deploy ERPNext using matching Frappe Docker files, MariaDB and Redis overrides, explicit site and app initialization, Caddy HTTPS and monitored queues. Secure roles and test complete backups before migrations.

ERPNext combines accounting, purchasing, inventory, sales, manufacturing, HR and projects on the Frappe framework. Self-hosting controls the deployment and data, but requires database, queues, permissions and recovery maintenance. This guide uses Ubuntu 24.04, Docker Compose and official frappe_docker containers.
| Workload | CPU | RAM | Disk | Operational starting point |
|---|---|---|---|---|
| Personal lab | 2 vCPU | 4 GB | 60 GB SSD | Limit concurrency without disabling required queues |
| Small team | 4 vCPU | 8 GB | 120 GB NVMe | Separate backup capacity and tested SMTP |
| Multiple companies/manufacturing | 8 vCPU+ | 16 GB+ | 200 GB NVMe+ | Consider separating database, files and queues |
These are budgets, not throughput guarantees. A 2-GB VPS is usually a short evaluation environment. Aim to reserve roughly 30% RAM and 25% disk as operating headroom, then measure free -h, df -h and docker stats. See VPS sizing.
Set working DNS for erp.example.com. Permit required SSH/HTTP/HTTPS, keeping MariaDB and Redis private.
sudo apt update
sudo apt install -y ca-certificates curl git openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/erpnext
sudo chown -R "$USER":"$USER" /opt/erpnext
cd /opt/erpnext
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
Review the root-level installer or use supported Docker packages. Docker-group access is powerful. Do not deploy unreviewed changes from main indefinitely:
git fetch --tags
git tag --sort=-version:refname | head -n 10
git rev-parse HEAD
Record a tested commit and image tag/digest. Reverting code alone does not reverse a database migration.
The older filename .env.example appears in this setup pattern:
cp .env.example .env
openssl rand -hex 32
nano .env
chmod 600 .env
Check your selected repository revision. The current official template is example.env, and compose.yaml is a base that needs database/Redis/publication overrides or equivalent external services. pwd.yml is a disposable demo with demo credentials, not a production shortcut.
The following older values identify configuration concerns; SITE_NAME, ADMIN_PASSWORD and MYSQL_ROOT_PASSWORD are not universally consumed by the current base:
ERPNEXT_VERSION=v15
DB_PASSWORD=change-a-long-database-password
MYSQL_ROOT_PASSWORD=change-a-long-root-password
ADMIN_PASSWORD=change-a-long-admin-password
SITE_NAME=erp.example.com
HTTP_PUBLISH_PORT=8080
For the current single-host MariaDB/Redis/Caddy layout, copy example.env to .env, choose an exact supported ERPNEXT_VERSION, replace DB_PASSWORD, and add:
COMPOSE_FILE=compose.yaml:overrides/compose.mariadb.yaml:overrides/compose.redis.yaml:overrides/compose.noproxy.yaml
HTTP_PUBLISH_PORT=127.0.0.1:8080
Use overrides from that same revision and inspect the merged result. The current MariaDB override uses DB_PASSWORD for its root password; the sample value 123 must be replaced. Keep database/Redis unpublished and preserve the sites, db-data and redis-queue-data volumes.
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 backend
Keep configurator, backend, frontend, websocket and scheduler. The layout uses redis-cache and redis-queue; older templates may list queue-short, queue-default and queue-long. The current base has queue-short and queue-long, both serving default work, rather than a separate queue-default service. Use actual names for all checks. Protect expanded configuration because it can reveal secrets.
This profile command is valid only when your selected configuration actually defines it:
docker compose --profile create-site run --rm create-site
Otherwise create the site with bench new-site in the backend. The older manual example is:
docker compose exec backend bench new-site erp.example.com \
--mariadb-root-password "$MYSQL_ROOT_PASSWORD" \
--admin-password "$ADMIN_PASSWORD"
docker compose exec backend bench --site all list-apps
docker compose exec backend bench --site erp.example.com migrate
Use the real root/admin secrets through a protected mechanism; a Compose .env file does not automatically populate your host shell's variables. Set the site name to the intended hostname or deliberately configure FRAPPE_SITE_NAME_HEADER. Creating a Frappe site is not installing ERPNext: add --install-app erpnext to supported new-site syntax, or run docker compose exec backend bench --site erp.example.com install-app erpnext afterward. Verify list-apps before migrating.
Complete company, chart of accounts, warehouse and user-role setup. Use Administrator for initial administration, with restricted ordinary accounts for daily work.
Publish the frontend privately at 127.0.0.1:8080:
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
erp.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:8080
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://erp.example.com
Caddy manages certificates when DNS/80/443 are reachable. Its reverse_proxy supports WebSocket automatically. Keep Host, Upgrade and X-Forwarded-Proto correct and configure trusted forwarding addresses in the frontend. Use one gateway and apply HSTS/includeSubDomains only for working HTTPS domains.
Configure SMTP plus SPF, DKIM and DMARC. Verify PTR for the actual SMTP sender IP; a relay provider generally controls it. Test internal notifications before bulk sending.
- Separate finance, sales, inventory and read-only audit roles.
- Give integrations dedicated users/API keys, scoped access and rotation dates.
- Enable supported administrator MFA and restrict management access or use a VPN.
- Monitor
queue-short,queue-default,queue-longand scheduler according to the actual service layout; current templates need no invented queue-default container.
docker compose logs --tail=200 queue-short
docker compose logs --tail=200 queue-default
docker compose logs --tail=200 scheduler
docker compose exec backend bench --site erp.example.com show-pending-jobs
Adapt old service names before running the log commands. Diagnose Redis connectivity, worker memory, external API timeouts and repeatedly failing jobs before changing concurrency. Never delete Redis state blindly to clear a backlog.
Preserve sites, including public/private attachments, configuration and encryption keys, alongside the database:
docker compose exec backend bench --site erp.example.com backup --with-files
docker compose exec backend find sites/erp.example.com/private/backups -maxdepth 1 -type f
Check that backup files were created successfully. Copy them to the host, including .env, the effective Compose files and repository commit; encrypt offsite copies and keep .env out of Git:
mkdir -p /opt/erpnext/backups
docker cp "$(docker compose ps -q backend):/home/frappe/frappe-bench/sites/erp.example.com/private/backups" /opt/erpnext/backups/
cp .env /opt/erpnext/backups/
docker compose config > /opt/erpnext/backups/compose-$(date +%F).yaml
git rev-parse HEAD > /opt/erpnext/backups/frappe-docker-commit.txt
Retain site_config.json/common_site_config.json and the relevant encryption keys, not just a SQL file. Quiesce writes for a coherent file/database recovery point. At least monthly, restore to a temporary isolated instance and test database, attachments, login, queues and email with real sending disabled. See restore drills.
Record tags, digests, docker compose config, database and site backups. Replace the angle-bracket placeholder with a tested revision before using this sequence:
git fetch --tags
git checkout <tested-tag-or-commit>
docker compose pull
docker compose up -d
docker compose exec backend bench --site all migrate
docker compose logs --tail=200 backend
Follow release-specific intermediate upgrades and migrations. Afterward test login, lists, print formats, downloads, email and queues. If migration fails, stop further changes; a migrated production database must not be connected blindly to older code. Restore the matching backup in isolation before deciding how to recover.
Start with docker compose ps, then frontend/backend/Caddy logs. Verify private 8080, DNS and firewall, successful configurator completion and healthy dependencies.
Check websocket, Upgrade forwarding, HTTPS and browser errors. HTTP/HTTPS mixing can block socket connections.
Use docker stats --no-stream to identify database, backend or worker pressure. Reduce justified concurrency, remove only disposable images/logs, and increase capacity or separate the database when necessary. Analyze slow queries rather than restarting every service.
Check SMTP credentials, DNS, scheduler and queue logs. Verify the actual provider port and outbound policy: 25 restrictions matter for direct SMTP; relays often use 587/465. Do not assume all mail uses 25.
- Domain, HTTPS, WebSocket and renewal are verified.
- Required database, Redis, application, queue and scheduler services are healthy or completed as expected.
- Administrator MFA and ordinary permissions are tested.
- SMTP, SPF, DKIM and DMARC tests pass.
- Database, attachments,
sites,.envand version details have offsite copies. - An isolated restore is tested and its duration/missing items recorded.
A successful docker compose up is only the beginning. Version control, queue monitoring, permission boundaries and tested recovery make ERPNext maintainable.
Further reading: