erpnext/docs/COOLIFY_DEPLOY.md

Coolify deployment — Production ERPNext (+ HRMS, Lending, LMS)

Prerequisites

• Coolify v4+ with Docker Compose support
• Jenkins green build → image in Forgejo Packages
• 4 GB+ RAM (8 GB+ recommended)
• Compose file: docker-compose.yml

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 (Coolify UI)

Copy from coolify.env.example. Required before first deploy:

Variable	Set in Coolify?	Source
CUSTOM_IMAGE	yes	Jenkins artifact / dist/coolify-image.env
CUSTOM_TAG	yes	e.g. main-26933f3 (pin) or main
PULL_POLICY	yes	if_not_present (after host preload; see below)
DB_PASSWORD	yes	strong secret
ADMIN_PASSWORD	yes	Frappe Administrator password
INSTALL_APPS	yes	erpnext,payments,hrms,lending,lms
SITE_NAME	no (auto)	From Coolify domain via SERVICE_FQDN_FRONTEND
FRAPPE_SITE_NAME_HEADER	no (auto)	Same as domain via SERVICE_FQDN_FRONTEND

Coolify env cache: If you previously set SITE_NAME=erp.example.com in Coolify, delete it so compose defaults use your real domain. Changing docker-compose.yml defaults alone does not update stored values.

3. Domain (before first deploy)

1. Coolify → your service → Domains
2. Add domain, e.g. erp.aexoradao.com
3. Attach to service frontend, port 8080
4. Coolify writes SERVICE_FQDN_FRONTEND=erp.aexoradao.com into the stack .env
5. Compose sets:
   • create-site → SITE_NAME=erp.aexoradao.com
   • frontend → FRAPPE_SITE_NAME_HEADER=erp.aexoradao.com

Order matters: assign domain then deploy. If create-site runs with an empty site name, the stack exits with a clear error.

4. Preload image on Coolify host (required once per tag)

The custom image is ~1.2 GB. Coolify deploy can fail with exit code 255 while pulling large layers through Cloudflare/Traefik (you may see progress stop around ~100 MB).

On the Coolify server as root (SSH or Coolify terminal):

git clone https://git.aexoradao.com/epistemophiliac/erpnext.git /tmp/erpnext
cd /tmp/erpnext
export REGISTRY_USER=epistemophiliac
export REGISTRY_PASSWORD='<forgejo-token-with-package-read>'
export CUSTOM_TAG=main-26933f3   # from Jenkins dist/coolify-image.env
bash scripts/coolify/preload-image.sh

This copies from internal Forgejo (forgejo-vydgeq365afzmxe4s1d75fwv:3000) — same path Jenkins uses for push — and tags git.aexoradao.com/epistemophiliac/erpnext:<tag> locally.

Set PULL_POLICY=if_not_present in Coolify so redeploys skip the large pull.

5. First deploy

db → redis → configurator
  → create-site (install apps, ~10–20 min)
  → migrator → backend / workers / frontend

Login: https://your-domain — user Administrator, password = ADMIN_PASSWORD.

6. Upgrades

1. Jenkins builds new image → update CUSTOM_TAG in Coolify
2. Redeploy — migrator runs bench migrate

Troubleshooting

Symptom	Fix
SITE_NAME empty on create-site	Assign domain on frontend:8080 before deploy
Wrong site / 404 nginx	Delete old SITE_NAME in Coolify UI; ensure header matches domain
Site created with wrong name	Wipe sites volume or rename site manually — env change alone won't rename
Deploy fails at Downloading …/487MB / exit 255	Image is OK — run scripts/coolify/preload-image.sh on host, set PULL_POLICY=if_not_present, redeploy
Image pull failed	Check CUSTOM_IMAGE / CUSTOM_TAG in Forgejo Packages; preload on host for private/large registry