app-catalog-felhom.eu/REPORT.md

REPORT — image pinning: :latest eliminated from the catalog (2026-07-12)

Class: implementation (template change + sweep gate; push = deploy). Baseline: main @ 2ebe082 → (this commit). Scope: 5 compose image lines + new gate script

• CLAUDE.md rule. No healthcheck/env/format touch-ups; no controller change; no redeploys triggered.

Why

The controller's recovery-unit ImagePins (felhom-controller internal/backup/recovery_unit.go) pins the compose tag: restoring a :latest-pinned app re-pulls whatever :latest points to at restore time — potentially schema-incompatible with the data being restored. Load-bearing rule: a deployed app pins to the digest it is currently running (the pin never causes a version jump); undeployed apps pin to the latest verified upstream stable.

The five pins (old → new, with evidence)

App	New pin	Evidence (all gathered 2026-07-12)
calibre-web (DEPLOYED, demo 9201)	crocodilestick/calibre-web-automated:v4.0.6	Running RepoDigest on 9201: sha256:c31a738b6d5e…; Docker Hub tag v4.0.6 digest: sha256:c31a738b6d5e… — exact match (Scenario A: pin == running image; a newer tag would have violated the no-silent-upgrade guard)
bentopdf (undeployed)	ghcr.io/alam00000/bentopdf:v2.8.6	GitHub latest release v2.8.6 (2026-06-28); ghcr manifest digest sha256:eaeea1e4… == latest
papra (undeployed)	ghcr.io/papra-hq/papra:26.6.1-rootless	ghcr latest digest sha256:a7a42e22… == 26.6.1-rootless; the -root variant differs (c5757540…) — the rootless variant is what :latest was shipping, so behavior (permission semantics) is preserved exactly
recipe-importer (own image, undeployed)	gitea.dooplex.hu/admin/recipe-importer:v0.9.11	Its repo CHANGELOG declares v0.9.11 (2026-02-26); the registry already had v0.9.11 (build.sh pushes :VERSION+:latest together), digest sha256:f3cb617c… == latest — Scenario C's retag was unnecessary; no push performed
termix (undeployed)	ghcr.io/lukegus/termix:2.5.0	ghcr digests: latest == 2.5.0 == release-2.5.0 (sha256:4d337131…); bare CalVer tag chosen

All five docker manifest inspect <ref> checks ran on the build server (180) with per-command exit codes checked — 5× OK, zero pipe-swallowed.

templates.json: contains no image strings (legacy Portainer-era metadata) — untouched, per §4.3.

Sweep + red-proofs (§10 / Scenario D)

• New rerunnable gate: scripts/check-image-pins.py — scans every templates/*/docker-compose.yml image: line; fails on floating tags (latest,dev,nightly,edge,main,master) AND on untagged refs (implicit :latest); @sha256: counts as pinned; registry-port refs handled.
• Final run: image-pin gate OK — 53 templates, 0 unpinned images, exit 0.
• Red-proof 1 (floating tag): reverted termix to :latest → exit 1 with templates/termix/docker-compose.yml:11 … [floating tag :latest] → restored → exit 0. ✓
• Red-proof 2 (bare shape): stripped termix's tag entirely → exit 1 with [NO TAG (implicit :latest)] → restored → exit 0. ✓ (Both §7-D shapes proven.)

Fleet-deployment verification (Scenario B)

• demo 9201: docker ps — bentopdf/papra/termix/recipe-importer not deployed; calibre-web running from :latest (Up 4 hours at check time).
• felhotest (router.abonet.hu:33022): unreachable (connection refused).
• Peti's box: offline (dead fan, no ETA).
• Operator asked and approved proceeding: every pin is digest-identical to current :latest, so even a hidden deployment elsewhere sees zero change vs. the status quo on its next redeploy.

Git-sync no-op verification on 9201

• Pushed 71828a8; sync triggered via docker exec felhom-controller curl -s -X POST http://127.0.0.1:8080/api/sync → HTTP 200. (Gotcha confirmed: guest-netns 127.0.0.1:8080 is NOT reachable — the API must be curled from inside the controller container; the public-URL POST proxy gotcha also applies.)
• Synced file on 9201: /opt/docker/stacks/calibre-web/docker-compose.yml:21 now reads image: crocodilestick/calibre-web-automated:v4.0.6. ✓
• calibre-web container after sync: crocodilestick/calibre-web-automated:latest | Up 5 hours (healthy) — uptime unchanged, no restart; the running image's digest equals the v4.0.6 pin, so the next redeploy pulls the byte-identical image. ✓

Observations (not acted on)

• When Peti's box returns: check whether bentopdf/papra/termix/recipe-importer are deployed there; if any is running an OLDER digest than the pin, decide upgrade vs. per-node pin then. felhotest should get the same check when reachable again.
• papra upstream publishes only -root/-rootless variant tags — any future manual upgrade must keep the -rootless suffix or permissions semantics change.
• bentopdf's ghcr tags/list API returns a stale/partial page (newest listed was 1.15.3 while v2.8.6 exists and serves) — tag existence must be checked via manifest HEAD/inspect, not tags/list.
• recipe-importer's registry :latest remains published (allowed; only templates must not use it).