View source for ERPNext v15 Docker Setup Guide

FORCETOC
= ERPNext v15 — Docker Setup Guide =

''Based on the original tutorial by Rein Simacon. Updated 2025 | ERPNext v15.31.3 | Docker Compose v2''

== Purpose ==

This guide walks you through running ERPNext v15 on your local machine using Docker. A Docker-based setup starts faster and uses fewer resources than a virtual machine — making it ideal for:

* '''Students''' exploring ERPNext, database design, REST APIs, and webhooks in a live environment
* '''IT staff and evaluators''' testing ERPNext before committing to a full deployment
* '''Thin-client demos''' — ERPNext v15 can comfortably serve companies under 50 users on modest hardware

If you break something, you can tear it all down and start fresh in minutes.

== Default Credentials ==

{| class="wikitable"
|-
! Field !! Value
|-
| URL || <code>http://localhost:8080</code>
|-
| Username || <code>Administrator</code>
|-
| Password || <code>admin</code>
|}

'''⚠ These are for local testing only. Never expose this setup to the internet without changing passwords and adding HTTPS.'''

== Minimum Hardware Requirements ==

{| class="wikitable"
|-
! Resource !! Minimum !! Recommended
|-
| RAM || 4 GB || 8 GB
|-
| CPU || 2 cores || 4 cores
|-
| Disk || 10 GB free || 20 GB free
|}

RAM is the critical constraint. ERPNext runs multiple services simultaneously (MariaDB, Redis ×2, backend workers, scheduler, websocket, nginx). Less than 4 GB will cause containers to crash-loop.

== Architecture Overview ==

ERPNext in Docker is composed of several services that work together:

{| class="wikitable"
|-
! Service !! Role
|-
| <code>frontend</code> || Nginx reverse proxy — serves the web UI on port 8080
|-
| <code>backend</code> || Frappe/ERPNext Python application server
|-
| <code>websocket</code> || Node.js Socket.IO server for real-time updates
|-
| <code>queue-long</code> || Background worker for long-running jobs (imports, reports)
|-
| <code>queue-short</code> || Background worker for short jobs (emails, notifications)
|-
| <code>scheduler</code> || Cron-like service for scheduled tasks
|-
| <code>db</code> || MariaDB 10.6 database
|-
| <code>redis-cache</code> || In-memory cache for session and page data
|-
| <code>redis-queue</code> || Message broker for the job queues
|-
| <code>configurator</code> || One-time setup container (runs once, then exits)
|-
| <code>create-site</code> || One-time site creation container (runs once, then exits)
|}

== Step 1 — Install Docker ==

Install '''Docker Engine''' and the '''Docker Compose plugin''' (v2).

=== Windows ===

Download and install '''Docker Desktop''': [https://www.docker.com/products/docker-desktop/ docker.com/products/docker-desktop]

Docker Desktop bundles both Docker Engine and the Compose plugin.

=== Ubuntu / Debian Linux ===

<syntaxhighlight lang="bash">
# Install Docker Engine
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (so you don't need sudo every time)
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker compose version
</syntaxhighlight>

'''Note:''' This guide uses <code>docker compose</code> (v2, no hyphen). The older <code>docker-compose</code> (v1) is deprecated. If your system only has v1, replace <code>docker compose</code> with <code>docker-compose</code> in all commands below.

=== Useful References ===
* [https://christitus.com/docker-guide/ Chris Titus Docker Guide]
* [https://flathub.org/apps/com.github.sdv43.whaler Optional GUI for Linux (Flatpak — Whaler)]

== Step 2 — Create a Working Directory ==

<syntaxhighlight lang="bash">
mkdir -p ~/docker/erpnext
cd ~/docker/erpnext
</syntaxhighlight>

== Step 3 — Create the Docker Compose File ==

Create a file named <code>pwd.yml</code>:

<syntaxhighlight lang="bash">
nano pwd.yml
</syntaxhighlight>

Paste the following content:

<syntaxhighlight lang="yaml">
services:
  backend:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  configurator:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: none
    entrypoint:
      - bash
      - -c
    command:
      - >
        ls -1 apps > sites/apps.txt;
        bench set-config -g db_host $$DB_HOST;
        bench set-config -gp db_port $$DB_PORT;
        bench set-config -g redis_cache "redis://$$REDIS_CACHE";
        bench set-config -g redis_queue "redis://$$REDIS_QUEUE";
        bench set-config -g redis_socketio "redis://$$REDIS_QUEUE";
        bench set-config -gp socketio_port $$SOCKETIO_PORT;
    environment:
      DB_HOST: db
      DB_PORT: "3306"
      REDIS_CACHE: redis-cache:6379
      REDIS_QUEUE: redis-queue:6379
      SOCKETIO_PORT: "9000"
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  create-site:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: none
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs
    entrypoint:
      - bash
      - -c
    command:
      - >
        wait-for-it -t 120 db:3306;
        wait-for-it -t 120 redis-cache:6379;
        wait-for-it -t 120 redis-queue:6379;
        export start=`date +%s`;
        until [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".db_host // empty"` ]] && \
          [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_cache // empty"` ]] && \
          [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_queue // empty"` ]];
        do
          echo "Waiting for sites/common_site_config.json to be created";
          sleep 5;
          if (( `date +%s`-start > 120 )); then
            echo "could not find sites/common_site_config.json with required keys";
            exit 1
          fi
        done;
        echo "sites/common_site_config.json found";
        bench new-site --no-mariadb-socket --admin-password=admin --db-root-password=admin --install-app erpnext --set-default frontend;

  db:
    image: mariadb:10.6
    healthcheck:
      test: mysqladmin ping -h localhost --password=admin
      interval: 1s
      retries: 15
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --skip-character-set-client-handshake
      - --skip-innodb-read-only-compressed
    environment:
      MYSQL_ROOT_PASSWORD: admin
    volumes:
      - db-data:/var/lib/mysql

  frontend:
    image: frappe/erpnext:v15.31.3
    depends_on:
      - websocket
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - nginx-entrypoint.sh
    environment:
      BACKEND: backend:8000
      FRAPPE_SITE_NAME_HEADER: frontend
      SOCKETIO: websocket:9000
      UPSTREAM_REAL_IP_ADDRESS: 127.0.0.1
      UPSTREAM_REAL_IP_HEADER: X-Forwarded-For
      UPSTREAM_REAL_IP_RECURSIVE: "off"
      PROXY_READ_TIMEOUT: 120
      CLIENT_MAX_BODY_SIZE: 50m
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs
    ports:
      - "8080:8080"

  queue-long:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - long,default,short
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  queue-short:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - short,default
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  redis-queue:
    image: redis:6.2-alpine
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-queue-data:/data

  redis-cache:
    image: redis:6.2-alpine
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-cache-data:/data

  scheduler:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - schedule
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  websocket:
    image: frappe/erpnext:v15.31.3
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - node
      - /home/frappe/frappe-bench/apps/frappe/socketio.js
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

volumes:
  db-data:
  redis-queue-data:
  redis-cache-data:
  sites:
  logs:
</syntaxhighlight>

Save and exit: <code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>.

'''Tip:''' You can always get the latest version of this file from the official Frappe Docker repository: [https://github.com/frappe/frappe_docker/blob/main/pwd.yml frappe/frappe_docker — pwd.yml]

== Step 4 — Start ERPNext ==

From inside your working directory (<code>~/docker/erpnext</code>), run:

<syntaxhighlight lang="bash">
docker compose -p pwd -f pwd.yml up -d
</syntaxhighlight>

This will:
# Pull all required images from Docker Hub (~1–2 GB total on first run)
# Create the named volumes for data persistence
# Start all services in the background
# Run <code>configurator</code> and <code>create-site</code> once to initialize the database and site

'''First startup takes 3–10 minutes''' depending on your internet speed and hardware. The <code>create-site</code> container must complete before the UI becomes available.

== Step 5 — Verify the Containers ==

<syntaxhighlight lang="bash">
docker ps -a
</syntaxhighlight>

Expected output — you should see containers for <code>frontend</code>, <code>backend</code>, <code>websocket</code>, <code>queue-long</code>, <code>queue-short</code>, <code>scheduler</code>, <code>db</code>, <code>redis-cache</code>, and <code>redis-queue</code>.

The <code>configurator</code> and <code>create-site</code> containers will show <code>Exited (0)</code> — this is '''normal and expected'''. They are one-time setup containers.

If any persistent service shows <code>Restarting</code>, check its logs:

<syntaxhighlight lang="bash">
docker logs <container_name>
</syntaxhighlight>

== Step 6 — Allow Port 8080 (Linux Firewall) ==

If you are running on a Linux server with <code>ufw</code> enabled:

<syntaxhighlight lang="bash">
sudo ufw allow 8080/tcp
</syntaxhighlight>

If you are running on a cloud VM (GCP, AWS, Azure), also open port 8080 in your cloud firewall/security group settings.

== Step 7 — Access ERPNext in Your Browser ==

Open your browser and go to:

<pre>
http://localhost:8080
</pre>

If accessing from another machine on the same network, replace <code>localhost</code> with the host machine's IP address:

<pre>
http://192.168.x.x:8080
</pre>

== Step 8 — Log In ==

{| class="wikitable"
|-
! Field !! Value
|-
| Username || <code>Administrator</code>
|-
| Password || <code>admin</code>
|}

After logging in, you will be prompted to complete initial setup (site name, language, timezone, etc.).

To verify the installed version: click '''Help''' (top-right) → '''About'''.

== Day-to-Day Operations ==

=== Stop ERPNext ===

Always stop containers cleanly before shutting down your machine or taking a backup:

<syntaxhighlight lang="bash">
docker compose -p pwd -f pwd.yml stop
</syntaxhighlight>

To stop all running containers system-wide (use with caution):

<syntaxhighlight lang="bash">
docker stop $(docker ps -q)
</syntaxhighlight>

=== Start ERPNext Again ===

<syntaxhighlight lang="bash">
docker compose -p pwd -f pwd.yml up -d
</syntaxhighlight>

Use <code>up -d</code> to restart, not <code>start</code>. The <code>up</code> command ensures all dependencies and network links are re-established correctly.

=== View Live Logs ===

<syntaxhighlight lang="bash">
docker compose -p pwd -f pwd.yml logs -f
</syntaxhighlight>

To follow logs for a specific service only (e.g., the backend):

<syntaxhighlight lang="bash">
docker compose -p pwd -f pwd.yml logs -f backend
</syntaxhighlight>

== Data Persistence ==

All your ERPNext data (database records, uploaded files, site configuration) is stored in '''Docker named volumes''', not inside the containers. This means:

* Stopping or restarting containers '''does not delete your data'''
* Deleting containers with <code>docker rm</code> '''does not delete your data'''
* Only explicitly removing volumes will delete data

To list volumes:

<syntaxhighlight lang="bash">
docker volume ls
</syntaxhighlight>

To back up the database volume:

<syntaxhighlight lang="bash">
docker exec pwd-db-1 mysqldump -u root -padmin --all-databases > erpnext_backup_$(date +%Y%m%d).sql
</syntaxhighlight>

== Nuclear Reset (Start Fresh) ==

If your setup is broken and you want to wipe everything and start over:

<syntaxhighlight lang="bash">
# Stop and remove all containers
docker compose -p pwd -f pwd.yml down

# Remove all containers, volumes, and images (DESTROYS ALL DATA)
docker compose -p pwd -f pwd.yml down -v --rmi all
</syntaxhighlight>

Or to remove '''all''' Docker containers on the system (use with caution):

<syntaxhighlight lang="bash">
docker rm -v -f $(docker ps -qa)
</syntaxhighlight>

After a full reset, rerun Step 4 to start fresh.

== Troubleshooting ==

{| class="wikitable"
|-
! Symptom !! Likely Cause !! Fix
|-
| Browser shows "connection refused" || Containers still starting up || Wait 3–5 more minutes, recheck <code>docker ps</code>
|-
| <code>frontend</code> container keeps restarting || Not enough RAM || Free up memory or add swap
|-
| <code>create-site</code> exited with error || DB not ready in time || Run <code>docker compose -p pwd -f pwd.yml down -v</code> then <code>up -d</code> again
|-
| Login works but page is blank || Browser cache issue || Hard refresh (<code>Ctrl+Shift+R</code>)
|-
| Changes not saving || Disk full || Check with <code>df -h</code>
|}

== Next Steps for Students ==

Once your ERPNext instance is running, here are good things to explore:

* '''REST API''' — ERPNext has a built-in REST API. Try: <code>http://localhost:8080/api/resource/DocType</code>
* '''Webhooks''' — Configure under Settings → Webhooks to push data on document events
* '''Custom DocTypes''' — Build your own data models without writing Python
* [https://frappeframework.com/docs Frappe Framework Docs]
* [https://docs.erpnext.com ERPNext Docs]
* [https://github.com/frappe/frappe_docker Frappe Docker repo]

----
''Original tutorial by Rein Simacon. Updated and expanded 2025.''

[[Category:Open Source]]
[[Category:Tutorials]]
[[Category:ERPNext]]
[[Category:Docker]]