Hosting ERPNext on a VPS: complete guide

An ERP centralises the company's most sensitive data: accounting entries, margins, customer and supplier records, payroll. SaaS offers often bill per user per month, which becomes costly as teams grow. On a dedicated VPS, you pay for the server once, you add as many users as needed, and the database stays under your control, backed up according to your own rules.

ERPNext is built on Frappe, a Python/JavaScript framework that keeps the source code readable and extensible. A self-hosted instance lets you update on your own schedule, choose add-on apps (HRMS, e-Commerce, Education, Healthcare) and write your own modules without relying on a vendor.

ERPNext covers the full operational cycle of a business. Accounting: multi-currency chart of accounts, general ledger, statutory reports (balance sheet, profit & loss), VAT management and bank reconciliation. Sales and purchasing: quotes, orders, deliveries, invoices and credit notes with approval workflows. Inventory management: multiple warehouses, batches and serial numbers, rolling stock counts, FIFO or moving-average valuation. CRM: leads, opportunities, campaigns and sales pipeline with an activity dashboard. Manufacturing: bill of materials (BOM), work orders, workstation and scrap tracking. HR: employee records, leave, attendance, country-configurable payroll and performance appraisals.

Each module is activated from the ERPNext desk; you only install what you need, and access rights are defined by role at the document level.

ERPNext is more demanding than average. Plan for at least 2 vCPU and 4 GB of RAM for test use, and 4 vCPU / 8 GB of RAM for production with several concurrent users. Allow 20 GB of disk for the MariaDB database, Redis and uploaded files.

On the software side: Docker and Docker Compose v2 (>= 2.20), a domain name (e.g. erp.myapp.com) pointing to the VPS IP, and port 443 open inbound. ERPNext uses MariaDB 10.6+ as its primary database and Redis for caching and real-time workers — both are included in the frappe_docker stack; you do not need to install them separately.

Once logged in as Administrator, go to Settings → System Settings to confirm the time zone and date format, then to Accounting → Chart of Accounts to adapt the structure to local standards (ERPNext provides charts of accounts for around a hundred countries).

Create your company under Accounting → Company: enter the base currency, tax number and opening fiscal year. ERPNext automatically creates the closing accounts and opening balance entries.

For users, go to Settings → Users and Permissions → User: assign business roles (Accounts Manager, Stock User, HR Manager…) rather than document-by-document rights. Roles combine: a user can be both Sales User and Purchase User without admin rights.

ERPNext provides several entry points for supervising a production instance.

bench doctor is the built-in diagnostic command: it checks the status of Celery workers, the scheduler and the Redis connection. Run it from the container:

docker compose exec backend bench doctor

A missing worker or blocked queue shows up immediately.

Application logs — ERPNext logs are in sites/<site>/logs/ inside the sites volume:
- web.log: HTTP errors and Python traces from the Gunicorn backend;
- worker.error.log: Celery worker exceptions (scheduled tasks, email sending);
- scheduler.log: scheduler cycles.

Automated backup — set up a cron job on the host to run bench backup daily and copy archives to remote storage:

0 3 * * * docker compose -p erpnext exec -T backend \
  bench --site erp.myapp.com backup --with-files \
  && rclone copy /path/to/backups remote:erpnext-backups

Updates — before each major version upgrade, do a full backup, read the release notes, test on a copy, then: bench update --reset inside the container. Schema migrations apply automatically, but some major ERPNext versions require upgrading to the highest minor version first (e.g. v14 → v14.x latest before moving to v15).

Worker crash: RedisBroadcastError or ConnectionRefusedError to Redis
Error in worker.error.log: redis.exceptions.ConnectionRefusedError: [Errno 111] Connection refused. Cause: the Redis container stopped or restarted after an OOM. Check: docker compose ps redis — if it is in Exited, restart with docker compose up -d redis then restart workers. If the crash recurs, increase the VPS RAM or limit the worker count in common_site_config.json.

Schema migration stuck: frappe.exceptions.SchemaChangedError
Error during bench migrate: SchemaChangedError: <DocType> has been manually modified. Cause: a column was manually changed in the database, ERPNext refuses to overwrite. Fix: bench --site erp.myapp.com migrate --skip-failing, then inspect the affected doctype in the UI and rerun migrate without the flag.

Bench timeout: Traceback ... requests.exceptions.ReadTimeout
Error during a long action (mass CSV import, inventory recalculation): ReadTimeout: HTTPConnectionPool. Increase the Gunicorn timeout in common_site_config.json: "gunicorn_workers": 2, "web_timeout": 120. Restart the web service: docker compose restart backend.

MariaDB connection refused: OperationalError: (2003, "Can't connect to MySQL server on 'db'")
Error at bench new-site or worker startup. Usual cause: the MariaDB container is not ready yet or the health check failed. Check: docker compose logs db | tail -20. If MariaDB shows [ERROR] InnoDB: Page 0 log sequence number, the database files are corrupted — restore from the last backup. If it is just a startup delay, wait 30 seconds and rerun the command.

Blank site after bench migrate: TemplateNotFound
ERPNext shows a blank page or Jinja error after an update. Cause: static assets were not rebuilt. Run: docker compose exec backend bench --site erp.myapp.com clear-cache && bench build --app erpnext. Restarting the frontend container (if separate) may also suffice.