erpnext/docs/JENKINS.md

Jenkins CI — custom image build + Forgejo registry

Repo: https://git.aexoradao.com/epistemophiliac/erpnext.git
Branch: main
Registry image: git.aexoradao.com/epistemophiliac/erpnext

What Jenkins does

Stage	Purpose
Verify	Required files including apps.json, Containerfile
Production readiness	Secrets/docs/compose checks
Bootstrap Docker tools	Static docker CLI + compose, socket access
Compose validate	Coolify-safe docker compose config
Build custom image	bench init from apps.json (ERPNext, HRMS, Lending, LMS, payments)
Push to Forgejo registry	Tags main-<git-sha> and main
Verify registry pull	Confirms the pushed image is pullable

Artifacts: dist/coolify-image.env, dist/docker-compose.coolify.yml, dist/image-reference.txt

First image build can take 30–60+ minutes (compiles assets). Later builds use Docker layer cache unless apps.json changes.

Jenkins job setup

Same as before — Pipeline from SCM or Multibranch with Discover branches.

Credentials: forgejo-erpnext (username + Forgejo token) — used for git checkout and docker login git.aexoradao.com.

Token needs:

• Repo read (checkout)
• Package write (push container images to Forgejo registry)

Enable Packages on the Forgejo repo if pushes fail with 404/403.

After a green build

Download dist/coolify-image.env from Jenkins artifacts, or use:

CUSTOM_IMAGE=git.aexoradao.com/epistemophiliac/erpnext
CUSTOM_TAG=main-<commit-sha>
PULL_POLICY=always

Set those in Coolify before deploy (or use CUSTOM_TAG=main for latest main build).

Changing apps (HRMS, Lending, LMS, …)

1. Edit apps.json (branches must match FRAPPE_BRANCH=version-16 where applicable)
2. Push to main
3. Jenkins rebuilds and pushes a new image tag
4. Update CUSTOM_TAG in Coolify and redeploy

Troubleshooting

Build fails: BuildKit is enabled but the buildx component is missing

The bootstrap stage installs the buildx CLI plugin into .ci-bin/docker-config/cli-plugins/. If this regresses, re-run Build Now on latest main (not Rebuild on an old commit).

permission denied on /var/run/docker.sock

Set DOCKER_GID on the Jenkins Coolify service to the host docker group GID (stat -c '%g' /var/run/docker.sock), redeploy Jenkins.

Registry push 413 Payload Too Large

Docker image layers are often >100MB. If git.aexoradao.com is behind Cloudflare proxy (orange cloud), uploads fail with 413.

Why Jenkins extra_hosts alone is not enough: with /var/run/docker.sock mounted, docker push runs on the host dockerd, which uses the host's DNS//etc/hosts, not the Jenkins container's.

Fix applied in CI: jenkins-registry-bypass.sh adds on the Coolify host:

127.0.0.1 git.aexoradao.com

(via a one-shot docker run --network host container). Pushes then go to local Traefik, not Cloudflare.

Manual fallback: Cloudflare DNS → DNS only (grey cloud) for git.aexoradao.com, or add the same line to the host /etc/hosts yourself.

Registry push 401/403

• Token needs write:package (or full repo scope including packages)
• docker login git.aexoradao.com with same credentials as git

Build fails on bench init

• All apps in apps.json must be compatible with version-16
• LMS has no version-16 branch — pinned to tag v2.55.0 in apps.json

source: not found

All pipeline steps use bash scripts/ci/*.sh — do not use source in bare sh ''' blocks.

Use Build Now, not Rebuild on old runs

Rebuild replays an old commit.