admin
2b22a23d60
Campaign 10's R-156 found papra writing its database into the container's writable layer while the volume the template preserves stayed empty — a backup that completes, verifies, and contains nothing. papra was never the point: nothing anywhere checked that the folder a template preserves is the folder the app writes to. All 53 templates have now been measured live. 43 CLEAN / 3 BROKEN / 7 UNDETERMINED. UNDETERMINED is counted separately, each with its reason, and never folded into CLEAN. FIXED (neither app is deployed anywhere, so nothing was stranded): - gramps-web mounted /app/data, /app/media, /tmp — and /app/data is a path the application never writes. Its accounts database and ITS FAMILY TREE both landed in the writable layer while gramps_data was tarred nightly as an empty directory. Now persists the eight paths the image's own environment names, matching upstream's reference compose. Proven: users.sqlite and the family-tree files survive a redeploy byte-identical, same inode. - wishlist mounted wishlist_data:/data, another path the app never writes; prod.db landed in the ANONYMOUS volume from the image's VOLUME directive — absent from ResolveDockerVolumeNames, so never backed up, and orphaned by a redeploy. Now mounts /usr/src/app/data + /usr/src/app/uploads. Proven: prod.db byte-identical, same inode, across a redeploy. Every corrected path confirmed by two independent sources — the shipped image's own environment/Config.Volumes and upstream's reference compose — never inferred from a directory name. papra is NOT fixed. It is live on one box, and changing the mount target makes the next compose up recreate the container and destroy the writable layer its documents live in. The fix is prepared and proven in the scratch guest (current: db.sqlite differs after a redeploy, so a real account created via the API is lost; fixed: byte-identical, it survives). Referred to the operator with the two options; no migration written. NEW GATE scripts/check-volume-persistence.py — the third catalog gate and the only RUNTIME one. This class is invisible to static analysis, measured not assumed: a static audit of all 53 composes reports the catalog clean AND reports papra clean. Exit 0 clean / 1 REFUSED / 2 undecided. It refuses to report at all unless it has just re-proven itself in both directions against two canary templates that differ only in which path the volume mounts at, so every run carries a live demonstration of R-156 and of its fix. No docker exec anywhere (Campaign 7 §1.1). 44 fixture tests driving check(), the function __main__ calls; every rule red-proofed. Enforcement is convention, not CI — this repo has no CI. Stated plainly in the report; raising it is proposed as R-160. Report, per-app evidence, proofs and proposed register entries (R-158..R-161, NOT filed — felhom.eu is fenced this session): audits/persistence-sweep-2026-08-02/
4.3 KiB
4.3 KiB
CLAUDE.md — app-catalog-felhom.eu
Loads when Claude Code touches this repo. Current state:
CONTEXT.md+CHANGELOG.mdtop. Cross-repo orientation: workspace-root/mnt/5_hdd/felhom.eu/git/CLAUDE.md.
What this repo is
The Felhom app catalog: one directory per app under templates/<app>/, each holding exactly
docker-compose.yml + .felhom.yml (deploy fields, resources, healthcheck probe, app_info — all
customer-facing text in Hungarian). The felhom-controller git-syncs these to every customer box;
.felhom.yml drives the deploy wizard. templates.json + scripts/generate-customer.sh are LEGACY
(Portainer-era) — new apps don't touch them.
Deploy contract
Push to main = deploy. The controller's sync picks changes up within 15 minutes (or trigger via
the dashboard "Sablonok frissítése" button / POST /api/sync). Only the two template files sync;
deployed app.yaml (customer secrets) is never overwritten. Full deploy details: the
felhom-build-deploy skill.
Conventions
- See
REUSE.mdbefore adding or editing an app — canonical example app (paperless-ngx), required.felhom.ymlfields, healthcheck family per image type, memory-limit rules, traps. - Update
REUSE.mdin the same commit that changes a catalog-wide convention. README.mdis the format spec — update its app tables when adding an app.- Update
CHANGELOG.md(newest on top) and overwriteREPORT.mdwith every pushed change. - No secrets in any committed file; secrets are generated at deploy time via
deploy_fieldsgenerate:specs. - Never
:latestor untagged images in templates — pin a concrete version tag; an app deployed anywhere in the fleet is pinned to the digest it is currently running (a pin must never cause a version jump). Digest pins (@sha256:) also count. Gate:python scripts/check-image-pins.py(run after any compose change; exit 1 on any floating/missing tag). - A pinned tag can still rot away upstream — the pin gate is syntactic and cannot see that.
Second gate:
python3 scripts/check-image-resolvable.py(exit 0 resolve / 1 GONE / 2 inconclusive), run at the start of every catalog campaign and before any publish train that vouches the catalog. Needs network +docker; unauthenticated Docker Hub throttles a full sweep, sodocker loginfirst or expect exit 2. It reports a throttle as INCONCLUSIVE, never as a dead image. - A well-formed template can still preserve the wrong folder — and no static check can see it.
Third gate, the only RUNTIME one:
python3 scripts/check-volume-persistence.py(0 all clean / 1 REFUSED / 2 undecided). It deploys each template, exercises it into writing data, and compares where the data landed against what the compose mounts. Needs Docker + network and minutes per app, so it is periodic like the resolvability gate — run it whenever a template'svolumes:block or image tag changes, and at the start of every catalog campaign, on a scratch host, never a customer box. It refuses to report at all unless it has just re-proven itself in both directions against two canary templates. Fixture tests (no Docker):python3 scripts/test_check_volume_persistence.py. UNDETERMINED is exit 2 and is never a pass — an app that wrote nothing has not been shown to be correct. Why it exists: papra mountedpapra_data:/app/datawhile the app wrote its database to/app/app-data/db/, so its backup completed, verified, and contained an empty directory (R-156, Campaign 10). - Taking an app out of circulation — use
lifecycle:, never a directory move..felhom.ymlgains an optionallifecycle:field:available(default; absent/empty means this),hidden(not offered for new installs, no explanation owed),abandoned(upstream stopped developing it — not offered for new installs, and every box already running it shows a permanent "Nem karbantartott" notice). Deployed instances keep working in full either way — the state affects what is OFFERED, never what already runs, and the controller REFUSES a deploy of a non-available template server-side. An unknown value degrades toavailablewith one WARN, so a typo can never brick a template. This supersedes the short-livedretired/directory move, which was wrong: removing a template orphans every customer already running it.