admin
a32541684a
Moving a template out of templates/ un-offers it but also makes the controller's orphan detector see it as GONE for anyone already running the app - flagging their working install Elavult with a Torles button. Withdrawing an app must never take a working app away from a customer. Optional lifecycle: available|hidden|abandoned in .felhom.yml instead. plant-it returns to templates/ as the first abandoned app; retired/ removed. Resolvability gate skips (and reports) non-available apps.
3.2 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. - 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.