epistemophiliac 4126cbf737 Load ERPNext image internally on Coolify deploy via Skopeo.

Add image-preload init service on Forgejo Docker network, default PULL_POLICY never, and preload host docker after Jenkins push.

2026-06-16 20:58:32 -04:00

3.6 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	`never` (image-preload loads internally)
`REGISTRY_USER`	yes	Forgejo username
`REGISTRY_PASSWORD`	yes	Forgejo token (package read)
`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)

Coolify → your service → Domains
Add domain, e.g. erp.aexoradao.com
Attach to service frontend, port 8080
Coolify writes SERVICE_FQDN_FRONTEND=erp.aexoradao.com into the stack .env
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. Internal image load (automatic)

Compose includes an image-preload init service (Skopeo → internal Forgejo, same path as Jenkins push). It copies the image into host Docker before ERPNext services start — no Cloudflare pull.

Required Coolify env vars (see coolify.env.example):

REGISTRY_USER=epistemophiliac
REGISTRY_PASSWORD=<forgejo-token>
CUSTOM_IMAGE=git.aexoradao.com/epistemophiliac/erpnext
CUSTOM_TAG=main-26933f3
PULL_POLICY=never

Jenkins also preloads the host after each green build, so redeploys are fast.

5. First deploy

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

6. Upgrades

Jenkins builds new image → update CUSTOM_TAG in Coolify
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

3.6 KiB Raw Blame History Unescape Escape