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

@@ -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

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

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='<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
 
 ```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 |

scripts/ci/jenkins-build-image.sh

@@ -33,7 +33,7 @@ echo "${REGISTRY_IMAGE}:${IMAGE_TAG}" > dist/image-reference.txt
 cat > dist/coolify-image.env <<EOF
 CUSTOM_IMAGE=${REGISTRY_IMAGE}
 CUSTOM_TAG=${IMAGE_TAG}
-PULL_POLICY=always
+PULL_POLICY=if_not_present
 EOF
 
 echo "Built ${REGISTRY_IMAGE}:${IMAGE_TAG} and ${REGISTRY_IMAGE}:main"

scripts/coolify/preload-image.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Pre-load the ERPNext custom image into the Coolify host Docker daemon.
+# Run on the Coolify server (root) BEFORE the first deploy, or after Jenkins pushes a new tag.
+#
+# Why: the custom image is ~1.2GB with large layers. Coolify deploy can fail while
+# `docker compose up` streams pull progress (exit 255) when pulling through Cloudflare/Traefik.
+# Skopeo copies from internal Forgejo (same trick as Jenkins push) — fast and reliable.
+#
+# Usage (on Coolify host):
+#   export REGISTRY_USER=epistemophiliac
+#   export REGISTRY_PASSWORD='<forgejo-token>'
+#   export CUSTOM_TAG=main-26933f3   # or main
+#   bash scripts/coolify/preload-image.sh
+#
+# Then in Coolify env: PULL_POLICY=if_not_present
+set -euo pipefail
+
+REGISTRY_IMAGE="${CUSTOM_IMAGE:-git.aexoradao.com/epistemophiliac/erpnext}"
+IMAGE_TAG="${CUSTOM_TAG:-main}"
+FORGEJO_HOST="${FORGEJO_HOST:-forgejo-vydgeq365afzmxe4s1d75fwv}"
+FORGEJO_NETWORK="${FORGEJO_NETWORK:-vydgeq365afzmxe4s1d75fwv}"
+SKOPEO_IMAGE="${SKOPEO_IMAGE:-quay.io/skopeo/stable:v1.17.0}"
+
+if [ -z "${REGISTRY_USER:-}" ] || [ -z "${REGISTRY_PASSWORD:-}" ]; then
+  echo "ERROR: set REGISTRY_USER and REGISTRY_PASSWORD (Forgejo token with package read)"
+  exit 1
+fi
+
+if ! docker info >/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."