Correct host image cleanup: prune dangling only, keep tagged :latest
CI Smoke / toolchain (push) Successful in 2s

The previous cleanup guidance removed the tagged :latest after push,
which deleted images still deployed on the Unraid host. Replace with
a dangling-only prune in both the troubleshooting doc and the sample
docker-build-push workflow; validated on jason/wfh (reclaimed 4.3GB).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jason Stedwell
2026-07-02 09:25:25 -05:00
parent 1c679e3752
commit bac6129d78
2 changed files with 23 additions and 13 deletions
+15 -13
View File
@@ -158,26 +158,28 @@ 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:
**Fix:** Have Docker-build workflows prune dangling images after pushing:
```yaml
- name: Clean up build images on host
- name: Prune dangling 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)
run: docker image prune -f 2>/dev/null || true # 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.
`docker image prune -f` only removes **dangling** images — untagged leftovers from
previous builds. It never touches tagged images (the freshly built `:latest`, base
images) or any image a container references, even a stopped one. This matters when
the built `:latest` is itself deployed on the host (e.g. as an Unraid container):
do **not** add `docker image rm "${IMAGE}:latest"` to the cleanup — that deletes
the local tagged image out from under the deployment. The tagged image will still
show as "(orphan image)" on the Unraid Docker page unless a template container
uses it; that label is cosmetic, not a problem.
**One-time cleanup** of images left by earlier builds (run on the host):
Note the prune acts host-wide — fine on a dedicated runner host; be aware if the
host runs unrelated build tooling.
**One-time cleanup** of untagged leftovers from 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
```