Skip to content

ERPNext compose file gotcha

The ERPNext stack on biz-apps (CT 104, 192.168.86.194) deploys via /opt/frappe_docker/pwd.yml, the official Frappe "production with database" quickstart file.

/opt/frappe_docker/compose.yaml also exists but is the upstream parameterized template that expects ERPNEXT_VERSION / CUSTOM_IMAGE env vars. Those env vars are not set on this host. Running plain docker compose pull or docker compose up -d picks up compose.yaml and recreates containers with empty image tags, breaking the stack.

Correct commands

cd /opt/frappe_docker
docker compose -f pwd.yml ps
docker compose -f pwd.yml pull
docker compose -f pwd.yml up -d
docker compose -f pwd.yml logs <service>

How to verify which file owns the stack

docker inspect frappe_docker-frontend-1 | grep compose.project.config_files
# Returns: "/opt/frappe_docker/pwd.yml"

pwd.yml characteristics

  • Hardcoded image tag frappe/erpnext:v16.16.0 (no env vars)
  • Compose project name frappe_docker
  • Network frappe_docker_frappe_network
  • Frontend container has nginx that won't resolve backend:8000 / websocket:9000 at startup if those services aren't running yet. Restart frontend after the rest of the stack is up if it gets stuck in a restart loop.

Recovery if compose.yaml was accidentally used

cd /opt/frappe_docker
docker compose -f pwd.yml up -d
# Wait ~30s for backend/websocket, then if frontend is restarting:
docker restart frappe_docker-frontend-1
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/   # expect 200

[Claude Code], 2026-05-15.