app-catalog-felhom.eu/REUSE.md

# REUSE.md — app-catalog-felhom.eu

> Before adding or editing an app, check here. Conventions to copy, traps to avoid.
> Maintenance: update in the SAME commit that changes a catalog-wide convention.
> Entries cite real files. Line numbers are landmarks only — reconfirm before editing.

## 1. Canonical helpers

None — this repo is templates/config, not code. See §2/§5.

## 2. Canonical patterns (copy structure from THE named file)

| Pattern | Canonical file | Key traits |
|---|---|---|
| **The one canonical example app** | `templates/paperless-ngx/` (both files) | Multi-container (app + postgres + redis), HDD + userdata mounts, full deploy_fields spectrum (domain/subdomain/secret/password/text/path/select). Copy this structure for any new app. |
| `.felhom.yml` required fields | `templates/paperless-ngx/.felhom.yml` | All 53 apps: `display_name`, `description` (Hungarian), `category`, `subdomain`, `slug`, `resources{mem_request, mem_limit, pi_compatible, needs_hdd}`, `deploy_fields`, `app_info{tagline, use_cases, first_steps, ...}`, `healthcheck`. Optional: `smtp_mapping` (email-capable apps), `open_path` (non-root landing page, e.g. ghost). |
| deploy_fields conventions | `templates/paperless-ngx/.felhom.yml` (`deploy_fields:` block) | Every app starts with `DOMAIN` (type `domain`) + `SUBDOMAIN` (type `subdomain`, `locked_after_deploy: true`). Secrets: `type: secret` + `generate:` — dominant generators `password:24` (DB passwords) and `hex:32` (app secret keys); `password:16` for shown admin passwords (`type: password`). HDD apps add `HDD_PATH` (`type: path`, placeholder `/mnt/felhom-drives/hdd_1`, locked). Labels/descriptions in Hungarian. |
| Controller-side health probe | `templates/vaultwarden/.felhom.yml` (`healthcheck:` block) | `healthcheck.checks[]` with `type: http` (port only), `type: api` (port + `path` + `expect.status: 200`), or `type: tcp` (port only — mealie, crafty-controller). Prefer `api` with a real health path when the app has one. |
| Image pinning | ALL `templates/*/docker-compose.yml` (`image:` line) | **Never `:latest` or untagged** (recovery-unit `ImagePins` pins the tag — `:latest` breaks restore fidelity). Pin a concrete version tag; an app deployed anywhere in the fleet pins to the digest it is RUNNING (pin ≠ upgrade); `@sha256:` digest pins also count. Gate: `python scripts/check-image-pins.py` after any compose change (swept 2026-07-12: 5 pins). TRAP: ghcr `tags/list` can be stale/partial — verify tag existence via `docker manifest inspect`, never the tag list. |
| Docker healthcheck host | ALL `templates/*/docker-compose.yml` (`healthcheck.test:`) | **Always `127.0.0.1`, never `localhost`.** BusyBox `wget` (and node/python/curl one-shots) resolve `localhost`→IPv6 `::1` with NO cross-address-family fallback; an app that binds IPv4-only then reads docker-`unhealthy` while fully serving (vaultwarden, re-run 2026-07-06 — swept all 48 templates). |
| Docker healthcheck — BusyBox/wget images | `templates/vaultwarden/docker-compose.yml` (~L49) | `test: ["CMD", "wget", "--spider", "-q", "http://localhost:<port>/<path>"]`. Most common family (~20 apps, e.g. homebox, glance). |
| Docker healthcheck — curl-capable images | `templates/paperless-ngx/docker-compose.yml` (~L76) | `test: ["CMD", "curl", "-f", "http://localhost:<port>/<path>"]` (~18 apps: jellyfin, immich, sonarr…). |
| Docker healthcheck — Node images (no wget/curl) | `templates/rallly/docker-compose.yml` (~L49) | `test: ["CMD", "node", "-e", "require('http').get(...)"]` — used when the image lacks wget (that was rallly's actual bug). |
| Docker healthcheck — Python images | `templates/mealie/docker-compose.yml` (~L47) | `test: ["CMD-SHELL", "python3 -c \"import socket; s=socket.create_connection(('localhost',<port>),2); s.close()\""]` (mealie, crafty-controller). tandoor/wger use `urllib.request` variants for real HTTP checks. |
| Docker healthcheck — DB/Redis sidecars | `templates/paperless-ngx/docker-compose.yml` (~L107, L129) | postgres: `pg_isready -U <user> -d <db>`; mariadb: `healthcheck.sh --connect --innodb_initialized`; redis: `redis-cli ping`. App container gets `depends_on: <db>: condition: service_healthy`. |
| Memory convention | `templates/paperless-ngx/docker-compose.yml` (~L71) + `.felhom.yml resources:` | EVERY service has `deploy.resources.limits.memory` (compose is the enforcement). NO `reservations` anywhere. `.felhom.yml mem_limit` = SUM of all containers' limits (see paperless header comment: 768+256+128=1152M); `mem_request` = expected steady-state usage, display-only. |
| Compose file skeleton | `templates/paperless-ngx/docker-compose.yml` (header) | Header comment (app, domain, DB type, RAM math, Pi), `restart: unless-stopped`, `TZ=Europe/Budapest`, explicit `container_name`, `traefik-public` external network + `<app>-internal` for DBs, Traefik labels with ``Host(`${SUBDOMAIN}.${DOMAIN}`)``, named volumes for DB/config (NVMe), `${HDD_PATH}/appdata/<app>/...` for bulk data, `${USERDATA_PATH}/...` for customer-browsable content. |
| App-email (SMTP shim) opt-in | `templates/vaultwarden/.felhom.yml` (`smtp_mapping:`) + README.md §smtp_mapping | `smtp_mapping` maps shim host/port/security/from to the app's own env names; compose MUST reference the mapped `${VAR:-}` keys with empty defaults. STARTTLS if the app can accept self-signed certs, else `security_value: "NONE"` plaintext (or the :2526 plaintext listener for STARTTLS-insistent clients — see calcom/nextcloud). TRAP: an image that treats defined-but-EMPTY mail vars as "set" (vaultwarden — campaign F1 2026-07-06) needs its own enable-flag gated `false` in compose and flipped `"true"` via `smtp_mapping.extra`; boot-prove a fresh email-off deploy for every new smtp-mapped app. |
| Probe-container naming | `templates/vaultwarden/docker-compose.yml` (`container_name: vaultwarden`) + `templates/sparkyfitness/` | The controller-side `healthcheck.checks[]` probe dials the container whose **name equals the stack (directory) name exactly**; fallback = the FIRST running prefix-match, which in a multi-container stack can be the DB (verified: `felhom-controller/internal/stacks/healthprobe.go` `findProbeContainer`). So the Traefik-exposed service's `container_name` must be exactly the stack name; sidecars `<app>-db`, `<app>-redis`, …. |

## 3. Dangerous lookalikes — do NOT copy

| Trap | Why it bites | Use instead |
|---|---|---|
| `templates/gokapi/docker-compose.yml` custom `entrypoint` seeding `config.json` + `--deployment-password` | One-off hack because Gokapi has no env-var headless setup (pinned to ConfigVersion 21 / v1.9.6). Copying this entrypoint pattern to another app will break on image updates. | Normal env-var config via `deploy_fields`; entrypoint-seeding only as last resort. |
| `templates.json` + `scripts/generate-customer.sh` | LEGACY Portainer-only mechanism (marked so in README.md). New apps do NOT need entries here; the controller syncs `templates/<app>/` directly. | Just `templates/<app>/{docker-compose.yml,.felhom.yml}`. |
| `templates/uptime-kuma/docker-compose.yml` `test: ["CMD", "extra/healthcheck"]` | Image-provided binary, unique to this image — not a portable pattern. | Pick the wget/curl/node/python family matching your image (§2). |

## 4. Seams & interfaces (cross-repo)

- Controller pulls this repo (default 15m) and copies `templates/<app>/docker-compose.yml` + `.felhom.yml` to `/opt/docker/stacks/<app>/`; it NEVER overwrites deployed `app.yaml` / `.env`; SHA-256 change detection. Contract description: `README.md` §"How It Works".
- `.felhom.yml` is the contract surface consumed by felhom-controller (repo `felhom-controller/`): `deploy_fields` drive the deploy wizard, `resources` the deploy screen hints, `healthcheck.checks` the controller-side probe, `smtp_mapping` the app-email injection at deploy/redeploy.
- Assets are NOT in this repo: logo/screenshots resolve from felhom.eu via `slug` (`{assets.base_url}/assets/{slug}-logo.webp` — see comment block in `templates/paperless-ngx/.felhom.yml`).
- Commit+push to main IS the deploy: the controller picks changes up on next sync.

## 5. Extension points (adding a new app)

1. `templates/<app>/docker-compose.yml` — copy `templates/paperless-ngx/docker-compose.yml` skeleton; every service needs `container_name`, `restart: unless-stopped`, `TZ=Europe/Budapest`, `deploy.resources.limits.memory`, a healthcheck (family per §2), Traefik labels on the web service, `traefik-public` external + `<app>-internal` network if it has a DB.
2. `templates/<app>/.felhom.yml` — copy `templates/paperless-ngx/.felhom.yml`; required keys per §2; DOMAIN + SUBDOMAIN fields always; `mem_limit` = sum of compose limits; Hungarian user-facing text; `healthcheck.checks` probe.
3. Update `README.md` App Catalog + Variable-types tables (convention — every existing app is listed).
4. Skip `templates.json` / `generate-customer.sh` (legacy, §3).
5. Email-capable app: add `smtp_mapping` + matching `${VAR:-}` compose lines (§2 last row).

## 6. Known inconsistencies (observed — NOT fixed)

- `README.md` lists `templates/filebrowser/` in the tree, but no such directory exists; conversely `templates/recipe-importer/` exists but is absent from README's tree and both catalog tables.
- `README.md` field-type table (§".felhom.yml Format") omits `subdomain` (used by all 53 apps) and `secret_input` (`templates/romm/.felhom.yml`), and lists `boolean` which no descriptor uses.
- `README.md` says `smtp_mapping` is "Currently mapped: Vaultwarden, Mealie" — six descriptors now carry it (calcom, gitea, mealie, nextcloud, rallly, vaultwarden).
- Healthcheck URL style drifts: `localhost` vs `127.0.0.1`, trailing-slash vs none, `curl -f` vs `curl -sf`, and two distinct Node one-liner styles (compact rallly vs verbose docmost).
- One unquoted generator value (`generate: password:24`) among otherwise-quoted `generate: "..."` values.
- The in-file comment block in `.felhom.yml` headers (e.g. `templates/paperless-ngx/.felhom.yml` "Generator types") omits `base64key:N`, which `README.md` documents and one app uses.