epistemophiliac/erpnext
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
erpnext/docs/COOLIFY_DEPLOY.md
epistemophiliac f2f7e6355d Wire Coolify domain to SITE_NAME and document env template 
SERVICE_FQDN_FRONTEND from the frontend domain drives site creation and nginx
headers; coolify.env.example adds CUSTOM_IMAGE/CUSTOM_TAG for Jenkins registry pulls.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-16 20:34:44 -04:00

2.7 KiB
Raw Blame History

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 always
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. First deploy

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

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

5. 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
Image pull failed Check CUSTOM_IMAGE / CUSTOM_TAG in Forgejo Packages