erpnext/docs/COOLIFY_DEPLOY.md

Coolify deployment — Production ERPNext

Prerequisites

• Coolify v4+ with Docker Compose support
• Server: minimum 4 GB RAM, 8 GB+ for production workloads
• Public domain (e.g. erp.yourdomain.com)

1. Create the Coolify service

Setting	Value
Type	Docker Compose
Repository	https://git.aexoradao.com/epistemophiliac/erpnext
Branch	main
Compose file	docker-compose.yml

2. Environment variables

Set these in Coolify → Service → Environment Variables before first deploy:

Variable	Required	Example	Notes
ERPNEXT_VERSION	yes	v16.22.0	Pin image tag
DB_PASSWORD	yes	strong secret	MariaDB root
SITE_NAME	yes	erp.yourdomain.com	Must match domain
ADMIN_PASSWORD	yes	strong secret	Frappe login
FRAPPE_SITE_NAME_HEADER	yes	same as SITE_NAME	Single-site routing
MIGRATE_SITES	no	true	Run migrate on redeploy

Coolify env cache: Changing defaults in docker-compose.yml does not update values already stored in Coolify. Edit them in the UI after changes.

3. Domain routing

1. Open the deployed service in Coolify
2. Add domain: erp.yourdomain.com
3. Attach domain to service frontend
4. Internal port: 8080 (Frappe nginx — not 80)

The compose file sets SERVICE_URL_FRONTEND_8080 so Coolify routes HTTPS to nginx correctly.

4. First deploy timeline

db (healthy) → redis → configurator (exit 0)
  → create-site (new-site + install-app erpnext, ~5–15 min)
  → migrator → backend / workers / frontend

Watch logs:

• create-site — site creation progress
• backend — gunicorn ready
• frontend — nginx on 8080

5. Post-deploy verification

From Coolify terminal on frontend:

curl -sI http://localhost:8080/

From your machine:

curl -sI https://erp.yourdomain.com/

Login at https://erp.yourdomain.com — user Administrator.

6. Upgrades

1. Bump ERPNEXT_VERSION in Coolify env vars
2. Redeploy — migrator runs bench --site all migrate
3. Confirm migrator logs show success

Troubleshooting

Symptom	Fix
Coolify 404	Domain on wrong service — must be frontend:8080
Site not found	SITE_NAME ≠ domain; fix FRAPPE_SITE_NAME_HEADER in UI
Stack unhealthy	Healthcheck port must be 8080 on frontend
create-site fails on redeploy	Should be idempotent — check sites/$SITE_NAME exists
Env change ignored	Update variable in Coolify UI, not only in git

What we intentionally omit

• No Traefik / nginx-proxy / Let's Encrypt in compose — Coolify handles TLS
• No ports: — Coolify proxy only
• No pwd.yml demo stack

CI / production gate

Every merge to main should pass the Jenkins pipeline (Jenkinsfile) before Coolify deploy.

Local check:

make ci