app-catalog-felhom.eu/REPORT.md

REPORT — Add SparkyFitness to the app catalog (+ live deploy & health check)

Date: 2026-06-28 Task class: Implementation — pure catalog addition (no Go/controller/agent/hub code change). Outcome: ✅ Template added, synced, deployed live on guest 9201, all 3 containers healthy, end-to-end /api path verified through the public edge. One acceptance item (interactive account register/login) was deliberately left for a human — see "NOT validated" below.

---

1. Confirmed baselines

Repo	Baseline	After
app-catalog-felhom.eu	main @ d7a6a17 (working tree clean; templates/sparkyfitness/ was 404)	template commit 4351d08, docs commit (this push)
felhom-controller (running on demo)	v0.87.0 (gitea.dooplex.hu/admin/felhom-controller:0.87.0, healthy on guest 9201)	unchanged — template proven-compatible against 0.87.0

The running controller renders this template's type: subdomain + data_key fields correctly (deploy screen showed Domain auto-filled, Subdomain sparky, and all 4 auto-secrets) — so no STOP condition; no controller patch was needed.

2. Files created

• templates/sparkyfitness/docker-compose.yml
• templates/sparkyfitness/.felhom.yml

Commits on main:

• 4351d08 — the two template files (after lint + image probes).
• (this push) — CHANGELOG + README + REPORT docs.

templates.json (legacy Portainer index) intentionally left untouched. No other catalog apps modified.

3. §1.3 image healthcheck-tooling findings (verified on build server 192.168.0.180, v0.17.2)

Image	Probe authored	Finding	Final probe kept
codewithcj/sparkyfitness_server:v0.17.2	node -e GET /api/health	NODE_OK (node on PATH via --entrypoint node)	kept the node-exec probe
codewithcj/sparkyfitness:v0.17.2 (frontend)	wget --spider	both present: /usr/bin/wget and /usr/bin/curl	kept the wget --spider probe

No probe changes were required. Compose lints clean (docker compose config -q with the 4 ${...} vars set to dummies → LINT_OK).

4. Deploy method + evidence

Method: real UI flow via claude-in-chrome (no hand-written app.yaml).

1. https://felhom.demo-felhom.eu → Alkalmazások → "Sablonok frissítése" (sync). App count 55→56, Telepíthető 52→53; SparkyFitness card appeared (/stacks/sparkyfitness/deploy).
2. Deploy screen: Domain auto = demo-felhom.eu; Subdomain default sparky; 4 secrets shown "Automatikusan generálva"; memory gate 696 MB / 1664 MB (41%) → fits, not refused (Scenario C did not trigger). Clicked "Telepítés indítása" → "Konfiguráció mentve" → containers started.

docker ps (guest 9201):

sparkyfitness-frontend  codewithcj/sparkyfitness:v0.17.2         Up (healthy)
sparkyfitness-server    codewithcj/sparkyfitness_server:v0.17.2  Up (healthy)
sparkyfitness-db        postgres:15-alpine                       Up (healthy)

Server log excerpts (clean — Scenario A):

[INFO] Successfully applied migration: ...20260622120000_add_water_estimated_to_exercise_entries.sql
[INFO] Ensuring permissions for role: "sparkyapp"
[INFO] Successfully ensured permissions for role: "sparkyapp"
[INFO] Permissions granted to application user.
[INFO] Successfully applied all RLS policies.
[AUTH] Better Auth handler successfully mounted.
[INFO] SparkyFitnessServer listening on port 3010
[INFO] Incoming request: GET /api/health

No crash loop; no EACCES on /app/SparkyFitnessServer/uploads. Both DB roles confirmed present in the DB (SELECT rolname ... → sparky, sparkyapp).

Secrets (Scenario B) — verified without exposing values (from docker inspect env of the server):

• SPARKY_FITNESS_API_ENCRYPTION_KEY length = 64 (hex:32 ✓)
• BETTER_AUTH_SECRET length = 64 (✓)
• SPARKY_FITNESS_FRONTEND_URL = https://sparky.demo-felhom.eu (public https ✓ — CORS/Better-Auth origin)
• SPARKY_FITNESS_DB_USER = sparky, SPARKY_FITNESS_APP_DB_USER = sparkyapp (two distinct roles ✓)
• SPARKY_FITNESS_DISABLE_SIGNUP = false (household can register ✓) All four secrets are locked_after_deploy; the two crypto keys carry data_key: true.

Browser checks:

• https://sparky.demo-felhom.eu/login → SparkyFitness native email/password login + Sign Up page loads over a valid TLS cert (no warning). No OIDC buttons (correct for the customer template).
• https://sparky.demo-felhom.eu/api/health (through the public Cloudflare edge → Traefik → frontend nginx /api proxy → server) → {"status":"UP"}. This proves the frontend→server proxy + public routing + TLS end-to-end.

5. NOT yet validated (explicit)

• Interactive account register + login. Deliberately not performed by me: creating an account / entering credentials to authenticate falls under a browser-safety guardrail (prohibited even on request). Everything up to the authenticated API path is proven (healthy server, /api/health proxied through the public edge, CORS origin correctly set). Recommended human step: open https://sparky.demo-felhom.eu, click Sign Up, register a throwaway account, confirm login reaches the dashboard (≈30s). Expected to pass given the verified config.
• Backup / restore of this app (incl. the data_key recovery path for the two crypto keys) — not exercised here.
• Upload body-size limits for profile/exercise images (the k3s ingress set proxy-body-size: 50m; the Felhom Traefik path was not size-tested).
• Garmin / MCP integrations — out of scope (commented out upstream; not enabled).

6. Observations (noticed, not acted on)

• Upstream's compose uses postgres:18 + :latest; per the validated k3s manifest we pinned postgres:15-alpine with an explicit PGDATA subdir — kept that proven path.
• The frontend image ships both wget and curl; the server image runs node as a valid exec entrypoint — both healthchecks are robust without extra tooling.
• Demo guest 9201 has only 2 GB total RAM; SparkyFitness mem_limit is 1792M. The mem_request (400M) gate passed and real usage is far below the limit, but on a 2 GB box co-tenancy headroom is thin — worth noting for nodes running several heavier apps.