app-catalog-felhom.eu/NEW-APP-CHECKLIST.md

# NEW-APP CHECKLIST — draft (reviewer, 2026-10-01)

**What this is.** The list of things every new catalog app must have measured and recorded BEFORE it reaches the live
catalog. Each item exists because something went wrong on a real app — the "why" column names it. The filled-in copy
per app is the app's **onboarding record**; a gate refuses a new app without a complete one.

**How to read an item.** Each answer is **done** (with an evidence path), **n/a** (with a one-line reason), or **open**
(blocks publishing). "Measured" means on the bench or on scratch guest 9202 through the product — never read from
upstream alone. Upstream reading is allowed to PLAN a test, never to CLOSE an item.

**Where it lives (proposed — CC confirms):** the checklist in `app-catalog-felhom.eu/NEW-APP-CHECKLIST.md`; one record per
app in `app-catalog-felhom.eu/onboarding/<app>.md` (outside `templates/`, so the box never syncs it — the controller copies
only `docker-compose.yml` and `.felhom.yml`, `sync.go:364`). The new app is tested from the drill catalog on 9202 and
reaches the live catalog only with a complete record.

---

## 0. Fit — should we offer it at all?

| # | Check | How | Why (what went wrong before) |
|---|---|---|---|
| 0.1 | Open-source licence; we pull the upstream image, never redistribute | read the repo | the business sells installation, not software |
| 0.2 | Upstream is alive: a release in the last 6 months, issues answered | read the repo | plant-it went `abandoned`, its image is gone |
| 0.3 | An official image with **version tags** (not `latest`-only), amd64 (+arm64 if Pi) | registry | pins and digests need real tags |
| 0.4 | **Telemetry / phone-home** — on by default? a switch to turn it off? | docs + one packet capture or log read on 9202 | data sovereignty is the pitch |
| 0.5 | Needs the internet at runtime (claim tokens, first-start downloads)? | docs + a first start | plex (plex.tv claim), adventurelog (world data), immich (geodata) |
| 0.6 | Needs ports other than HTTP(S)? The tunnel carries HTTP only | compose + docs | gitea SSH, media DLNA, game servers — say what the household loses |
| 0.7 | Phone / desktop apps: do they work through the tunnel and the setup gate? | docs + one real client if one exists | immich's phone app vs the gate (decision 46) |
| 0.8 | What a household gets from it, in one sentence (Hungarian) | — | the catalog card and `use_cases` |

## 1. Images and the database

| # | Check | How | Why |
|---|---|---|---|
| 1.1 | Every image pinned to a concrete tag; resolvable | `catalog_gates.py <app>` (gates 1, 2) | `:latest` breaks restore fidelity |
| 1.2 | Database engine and major = **what the app's own upstream compose runs** | upstream compose at the pinned tag | decision 42's rule; avoids an early conversion |
| 1.3 | MariaDB sidecar: `MARIADB_AUTO_UPGRADE=1`; PostgreSQL 18: mount at `/var/lib/postgresql` | compose | R-459; PG 18 refuses `/data` |
| 1.4 | The app migrates its own database at start, **or** the switch that makes it do so is set | an update on 9202, login read back | wger: no migration without `DJANGO_*` switch, update said "done", login 500 (R-738) |
| 1.5 | The app runs its production server, not a dev server | process list in the container | wger `runserver` (R-755) |
| 1.6 | Every secret the app needs is generated (no image default, no empty key) | compose + a login on 9202 | wger JWT key missing → login 500 (R-737) |

## 2. Storage and backup

| # | Check | How | Why |
|---|---|---|---|
| 2.1 | Every path the app writes is mounted — **measured** | gate 3, `check-volume-persistence.py <app>` | papra backed up an empty folder (R-156) |
| 2.2 | Where each path lives: named volume (NVMe) / `${HDD_PATH}/appdata` / `${USERDATA_PATH}` | compose, REUSE.md skeleton | the household can browse userdata, not appdata |
| 2.3 | Backup class for every HDD path (`mandatory` / `excluded` …) and `data_paths` labels | `.felhom.yml backup:` | DB rows that point at files need those files (07) |
| 2.4 | File owner / uid fits the box (PUID/PGID where the image wants them) | first start on 9202 | linuxserver images chown their tree |
| 2.5 | **A backup and a restore through the product, data read back** | 9202: seed → backup → remove → restore → read back | the promise is the restore, not the backup |
| 2.6 | "Remove with data" and "remove keep data" both work | 9202 | R-756 (refused with a folder present) |
| 2.7 | Off-site size estimate for a typical household | measured size after seed + a sentence | decision 50's size warning |

## 3. Accounts and strangers

| # | Check | How | Why |
|---|---|---|---|
| 3.1 | First-admin class (FIRST-ADMIN.md 1–6), **measured** | fresh install on 9202 | decision 45 |
| 3.2 | Known default login → `after_install` with a generated password (and name, if the name is public and lockable) | 9202: default fails, generated works, wrong fails | bookstack, calibre-web (decisions 45, 61) |
| 3.3 | Open first-run screen → `setup_gate` (+ probe that **flips**, measured before and after) | 9202 as a stranger | 32 apps, decision 46 |
| 3.4 | Open sign-up after the setup → `signup_block` / `after_setup` switch; case-insensitive | 9202 as a stranger | decisions 47–49 |
| 3.5 | The install window: a stranger reaches nothing before the password is replaced | poll once a second during install | R-741 |
| 3.6 | **Lock-out**: N wrong passwords by a stranger — who is locked (name / address / everyone), for how long | 9202 through traefik | mealie 24 h, wger everyone (R-747, R-752, R-753) |
| 3.7 | The household can change its password and add family members; the page says how | 9202 | `add_people` copy |
| 3.8 | Secrets pass to commands as arguments, never inside program code | review `after_install` | security review 2026-09-29 |

## 4. Health

| # | Check | How | Why |
|---|---|---|---|
| 4.1 | Compose healthcheck of the right family, `127.0.0.1` not `localhost` | REUSE.md §2 | vaultwarden IPv6 trap |
| 4.2 | The controller probe dials what the compose healthcheck dials; a real health path where one exists | gate 7 | a wrong probe stops a working app after an update (R-618) |
| 4.3 | Healthy within `start_period` on a **cold first start** (incl. one-time imports) | 9202, timed | immich geodata import |
| 4.4 | Negative control: a broken app reads unhealthy | stop the DB, read the status | a probe that is always green proves nothing |
| 4.5 | The probe-named container is the stack name; sidecars `<app>-db` … | compose | `findProbeContainer` fallback picks the DB |

## 5. Resources

| # | Check | How | Why |
|---|---|---|---|
| 5.1 | **First start from birth, swap OFF**: peak `anon`, `oom_kill` = 0 | bench, sampled every 2 s | immich DB killed at 512 MiB, hidden by swap on 9202 (R-732, R-733) |
| 5.2 | 10-minute light-load soak: peak < 80 % of the limit, 0 kills, 0 restarts | harness memory watch | romm OOM at +76 s (decision 22) |
| 5.3 | `mem_limit` in `.felhom.yml` = the sum of the compose limits | gate / review | immich's header was 128 MB off |
| 5.4 | Node/Java apps: does the heap size itself from the limit? | two watches at two limits | R-693 (docmost) |
| 5.5 | Pi-compatible (yes/no), disk it pulls (image size) | registry | old images filled 9202 (R-736) |

## 6. Updates

| # | Check | How | Why |
|---|---|---|---|
| 6.1 | An upgrade fixture: seed + read-back **through the app's own front door**, negative control | `upgrade_fixtures*.py` | without it the app never updates itself |
| 6.2 | A first ladder step proven on bench + 9202 (`--write-ladder`), **or** "manual only" with the reason | harness | 35 of 53 update at night; the rest need a person |
| 6.3 | The undo works on a real failure (one forced-fail case) | 9202 | zipline's real failed jump, undone in 20 s |
| 6.4 | `files_may_change` mark understood (which files change at start) | bench | immich's six marker files (R-734) |
| 6.5 | Tag shape is stable upstream (no `v` dropped, no flavour prefix) | tag list | gramps-web, jellyfin, kimai (R-731) |

## 7. Mail

| # | Check | How | Why |
|---|---|---|---|
| 7.1 | Sends mail? → `smtp_mapping` + `${VAR:-}` compose lines; a fresh install with mail OFF boots | 9202 | vaultwarden empty-vars trap |

## 8. Household-facing text and listing

| # | Check | How | Why |
|---|---|---|---|
| 8.1 | Hungarian + English, informal „te", no „kérjük"; parity green; freeze updated | `check-copy-i18n.py` | operator rule |
| 8.2 | `app_info`: tagline, use_cases, first_steps, default_creds (if any), add_people | read on 9202's page | the page is the manual |
| 8.3 | Logo + screenshots on felhom.eu by `slug` | the asset URL answers 200 | the card is blank otherwise |
| 8.4 | README tables, FIRST-ADMIN row, `category`, `catalog_since` | review | REUSE.md §5 |

## 9. Sign-off

| # | Check | How |
|---|---|---|
| 9.1 | `python3 scripts/catalog_gates.py <app>` — all green (exit 0) | bench / scratch |
| 9.2 | A fresh install on 9202 from the drill catalog, as a household and as a stranger, start to finish | 9202 |
| 9.3 | Every item above done or n/a-with-reason; every finding that is not fixed is a register row | the record |
| 9.4 | Published to the live catalog in ONE commit with its record | the gate checks |