From 1c679e3752a74ad562a525b9321efffdfe374b7c Mon Sep 17 00:00:00 2001 From: Jason Stedwell Date: Mon, 29 Jun 2026 23:08:42 -0500 Subject: [PATCH] docs: troubleshooting entry for host orphan-image accumulation Document why host-label builds leave orphan images on the Docker host and the post-push cleanup + one-time prune pattern. Co-Authored-By: Claude Opus 4.8 --- docs/troubleshooting.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1bd3432..72cda15 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -143,3 +143,41 @@ This is an image build problem — the binary should always be present if the im ```bash ./scripts/verify-runtime.sh custom-gitea-runner:latest ``` + +--- + +## Orphan images piling up on the host (disk filling) + +**Symptom:** The Unraid Docker page (or `docker images`) shows a growing list of +`(orphan image)` entries — both tagged (`registry.alwisp.com//:latest`) +and untagged (bare image IDs) — that nothing created intentionally. + +**Cause:** Jobs that run on the `host` label use the **host Docker daemon** via the +mounted socket. Every `docker build` leaves its output image on the host, and each +rebuild orphans the previous one (the moved tag leaves the old image dangling). +Multi-stage build layers add more. Nothing removes them automatically, so they +accumulate and consume the array. + +**Fix:** Have Docker-build workflows clean up after pushing to the registry: + +```yaml + - name: Clean up build images on host + if: always() + run: | + IMAGE="registry.alwisp.com/${{ gitea.repository }}" + docker image rm -f "${IMAGE}:latest" 2>/dev/null || true + docker image prune -f 2>/dev/null || true # removes dangling layers (host-wide) +``` + +The image lives in the registry after `docker push`, so removing the local copy is +safe. `docker image prune -f` only removes **dangling** (untagged) images, not +tagged base images, so rebuilds stay fast. Note it acts host-wide — fine on a +dedicated runner host; be aware if the host runs unrelated build tooling. + +**One-time cleanup** of images left by earlier builds (run on the host): + +```bash +docker images --format '{{.Repository}}:{{.Tag}}' \ + | grep '^registry.alwisp.com/' | xargs -r docker rmi -f +docker image prune -f +```