From e73912541efa13e939953557f0a1462cad02bd5f Mon Sep 17 00:00:00 2001 From: epistemophiliac Date: Tue, 16 Jun 2026 20:49:15 -0400 Subject: [PATCH] Add Coolify host image preload for large registry pulls. Document exit 255 during multi-hundred-MB layer downloads and default PULL_POLICY to if_not_present after preload. --- coolify.env.example | 3 +- docker-compose.yml | 2 +- docs/COOLIFY_DEPLOY.md | 30 ++++++++++++++--- scripts/ci/jenkins-build-image.sh | 2 +- scripts/coolify/preload-image.sh | 54 +++++++++++++++++++++++++++++++ 5 files changed, 83 insertions(+), 8 deletions(-) create mode 100755 scripts/coolify/preload-image.sh diff --git a/coolify.env.example b/coolify.env.example index 0fce5e4..06fd811 100644 --- a/coolify.env.example +++ b/coolify.env.example @@ -4,7 +4,8 @@ # --- Custom image (required — from Jenkins Forgejo registry) --- CUSTOM_IMAGE=git.aexoradao.com/epistemophiliac/erpnext CUSTOM_TAG=main-26933f3 -PULL_POLICY=always +# Use if_not_present after scripts/coolify/preload-image.sh on the Coolify host +PULL_POLICY=if_not_present # --- Secrets (required — change before first deploy) --- DB_PASSWORD=replace-with-strong-secret diff --git a/docker-compose.yml b/docker-compose.yml index 29e64ab..b94ab2d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,7 +6,7 @@ x-customizable-image: &customizable_image image: ${CUSTOM_IMAGE:-git.aexoradao.com/epistemophiliac/erpnext}:${CUSTOM_TAG:-main} - pull_policy: ${PULL_POLICY:-always} + pull_policy: ${PULL_POLICY:-if_not_present} restart: ${RESTART_POLICY:-unless-stopped} x-depends-on-configurator: &depends_on_configurator diff --git a/docs/COOLIFY_DEPLOY.md b/docs/COOLIFY_DEPLOY.md index f653f59..2dfc71a 100644 --- a/docs/COOLIFY_DEPLOY.md +++ b/docs/COOLIFY_DEPLOY.md @@ -24,7 +24,7 @@ Copy from [`coolify.env.example`](../coolify.env.example). **Required before fir |----------|----------------|--------| | `CUSTOM_IMAGE` | yes | Jenkins artifact / `dist/coolify-image.env` | | `CUSTOM_TAG` | yes | e.g. `main-26933f3` (pin) or `main` | -| `PULL_POLICY` | yes | `always` | +| `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` | @@ -45,17 +45,36 @@ Copy from [`coolify.env.example`](../coolify.env.example). **Required before fir **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 +## 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): + +```bash +git clone https://git.aexoradao.com/epistemophiliac/erpnext.git /tmp/erpnext +cd /tmp/erpnext +export REGISTRY_USER=epistemophiliac +export REGISTRY_PASSWORD='' +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:` locally. + +Set `PULL_POLICY=if_not_present` in Coolify so redeploys skip the large pull. + +## 5. First deploy ```text -pull CUSTOM_IMAGE:TAG → db → redis → configurator +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 +## 6. Upgrades 1. Jenkins builds new image → update `CUSTOM_TAG` in Coolify 2. Redeploy — `migrator` runs `bench migrate` @@ -67,4 +86,5 @@ Login: `https://your-domain` — user `Administrator`, password = `ADMIN_PASSWOR | `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 | +| 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 | diff --git a/scripts/ci/jenkins-build-image.sh b/scripts/ci/jenkins-build-image.sh index ccf3163..c7b54bd 100755 --- a/scripts/ci/jenkins-build-image.sh +++ b/scripts/ci/jenkins-build-image.sh @@ -33,7 +33,7 @@ echo "${REGISTRY_IMAGE}:${IMAGE_TAG}" > dist/image-reference.txt cat > dist/coolify-image.env </dev/null 2>&1; then + echo "ERROR: run as root on the Coolify host (docker info failed)" + exit 1 +fi + +echo "=== Preload ${REGISTRY_IMAGE}:${IMAGE_TAG} ===" +echo "Source: http://${FORGEJO_HOST}:3000/epistemophiliac/erpnext:${IMAGE_TAG} (internal)" + +docker run --rm \ + --network "${FORGEJO_NETWORK}" \ + -v /var/run/docker.sock:/var/run/docker.sock \ + "${SKOPEO_IMAGE}" \ + copy \ + "docker://${FORGEJO_HOST}:3000/epistemophiliac/erpnext:${IMAGE_TAG}" \ + "docker-daemon:${REGISTRY_IMAGE}:${IMAGE_TAG}" \ + --src-creds "${REGISTRY_USER}:${REGISTRY_PASSWORD}" \ + --src-tls-verify=false \ + --retry-times 3 + +if [ "${IMAGE_TAG}" != "main" ]; then + docker tag "${REGISTRY_IMAGE}:${IMAGE_TAG}" "${REGISTRY_IMAGE}:main" + echo "Also tagged ${REGISTRY_IMAGE}:main" +fi + +echo "OK: ${REGISTRY_IMAGE}:${IMAGE_TAG} is on the host." +echo "Set PULL_POLICY=if_not_present in Coolify, then redeploy."