From 658b995e531debcb89a9a2c8f1d3abbaa78fd9bc Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 14 Feb 2026 20:15:56 +0100 Subject: [PATCH] Update documentation for app info pages feature - CONTEXT.md: session 5 with app detail/info pages + optional config - README.md: add optional-config API endpoint, update version to 0.2.11 - CLAUDE.md: add app info page patterns to key patterns section Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 4 ++++ CONTEXT.md | 28 +++++++++++++++++++++++----- controller/README.md | 15 +++++++++------ 3 files changed, 36 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index be0dadf..9a56d4f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -171,6 +171,10 @@ manually via the dashboard "Sablonok frissítése" button. - Memory bar on deploy page uses two-segment stacked bar (committed = solid green, new = translucent green) - Deploy flow shows 3-step progress panel (config → containers → health), polls `GET /api/stacks/{name}` every 3s until running/unhealthy/timeout(120s) - Telepítés buttons have `checkBeforeDeploy()` onclick guard — fetches live state from API before navigating to deploy page +- App info pages at `/apps/{slug}` — detail view with use cases, setup guide, screenshots, optional config +- Optional config saves to `app.yaml` and restarts deployed apps via `docker compose up -d` +- `optional_config` fields in `.felhom.yml` define post-deploy configurable env vars (e.g., API keys) +- `app_info` in `.felhom.yml` provides tagline, use_cases, first_steps, prerequisites, default_creds, docs_url ## Git sync module (internal/sync) diff --git a/CONTEXT.md b/CONTEXT.md index f437188..aec6e52 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -7,7 +7,7 @@ > > Ask Claude Code: "Please update CONTEXT.md with what we did today" -Last updated: 2026-02-14 (session 4) +Last updated: 2026-02-14 (session 5) --- @@ -22,13 +22,31 @@ Last updated: 2026-02-14 (session 4) ## Current project state ### felhom-controller (this repo) -- **Version:** v0.2.1 +- **Version:** v0.2.11 - **Phase 1:** ✅ COMPLETE — Stack Manager + Deploy Flow - **First app deployed:** Paperless-ngx on demo-felhom.eu (2026-02-13) - **Running on:** demo-felhom (N100 mini PC) at 192.168.0.162:8080 - **All Phase 1 features working:** deploy, start/stop/restart/update, logs, health-aware states, auth -### What was just completed (2026-02-14 session 4) +### What was just completed (2026-02-14 session 5) +- **App detail/info pages** — new feature: + - New route: `GET /apps/{slug}` renders a full info page (was redirect to deploy page) + - Hero section with logo, tagline, resource badges + - Screenshots section (graceful — hidden via `onerror` if assets don't exist) + - Info cards: use cases, first steps, prerequisites, default credentials, docs link + - Optional config form with AJAX save (POST `/api/stacks/{name}/optional-config`) + - New `.felhom.yml` fields: `app_info` (tagline, use_cases, first_steps, prerequisites, default_creds, docs_url) and `optional_config` (groups of env var fields) + - New structs in `metadata.go`: `AppInfo`, `OptionalConfigGroup`, `OptionalConfigField` + - `UpdateOptionalConfig` in `deploy.go`: saves optional env vars to `app.yaml`, restarts deployed stacks with `docker compose up -d` to pick up new env vars + - Navigation updated: stack cards on dashboard/stacks pages now link to `/apps/{slug}`, deploy page has "Részletek" link back to info page +- **RoMM metadata updated** (app-catalog repo): + - Full `app_info` section: tagline, 5 use cases, 6 first steps, 3 prerequisites, default creds, docs URL + - 6 optional config fields for metadata providers: IGDB (client_id + secret), SteamGridDB, ScreenScraper (user + password), MobyGames + - docker-compose.yml updated with SCREENSCRAPER_USER, SCREENSCRAPER_PASSWORD, MOBYGAMES_API_KEY env vars + - Display name fixed: "ROMM" → "RomM" +- **Controller version:** v0.2.11 + +### Previously completed (2026-02-14 session 4) - **Fixed deploy race condition** in `internal/stacks/deploy.go`: - In-memory `Deployed` flag now set BEFORE `docker compose up -d` (compose up can take 30-60s for image pulls) - On failure: both in-memory state and disk (app.yaml) are reverted @@ -120,9 +138,9 @@ Last updated: 2026-02-14 (session 4) 7. Documentation: restart vs up -d for image updates ### What's next (priorities) -1. Build + deploy the updated controller with git sync module +1. Add `app_info` + `optional_config` to more apps (start with Immich, Mealie, Vaultwarden) 2. Deploy a second app (e.g., ActualBudget — simplest, or Immich — tests HDD + secrets) to validate all .felhom.yml files -3. Test git sync end-to-end: push a template change to app-catalog, verify controller picks it up +3. Add app screenshots to the asset pipeline (romm-screenshot-1.webp etc.) 4. Test on Raspberry Pi (pi-customer-1) 5. Add `paths.hdd_path` to demo-felhom controller.yaml to enable HDD bar 6. Phase 2 continued: CPU/temperature metrics, Healthchecks.io pings diff --git a/controller/README.md b/controller/README.md index 42eecbf..a2dc906 100644 --- a/controller/README.md +++ b/controller/README.md @@ -24,7 +24,7 @@ controller generates secrets, saves app.yaml, runs `docker compose up -d`, and t with Traefik routing and health checks. The dashboard correctly shows real-time container states including health substatus (starting → healthy → running). -Current version: **v0.2.1** +Current version: **v0.2.111** ### What works - Dashboard with live container state (green/orange/yellow/red) @@ -32,6 +32,8 @@ Current version: **v0.2.1** - Stack operations: start, stop, restart, update (pull + recreate) - Live-scrolling log viewer with auto-refresh (3s polling), pause/resume, and scroll position tracking - Deploy page doubles as config viewer (read-only mode for deployed apps) +- App detail/info pages with use cases, setup guide, screenshots, and optional config +- Optional config saves to `app.yaml` and restarts deployed apps (e.g., metadata provider API keys) - Periodic stack rescanning (every 2 minutes) - Manual rescan endpoint (`POST /api/stacks/rescan`) - Alphabetically sorted stack display (consistent card ordering) @@ -42,7 +44,7 @@ Current version: **v0.2.1** - Memory summary bar shown on deploy page before deployment - Felhom.eu logo SVG in sidebar and login page - Verbose debug logging with operation timing, post-start container state checks, and image pull detection -- Clickable app cards on dashboard and applications pages (navigate to detail/deploy page) +- Clickable app cards on dashboard and applications pages (navigate to info page) - Memory bar with two-segment visualization on deploy page (committed vs new app allocation) - Deployment progress UI: 3-step progress panel with real-time health polling (config → containers → health check) @@ -321,17 +323,17 @@ See `docs/BUILDING.md` for the full guide. ```bash # Quick build (current platform only) cd ~/build/felhom-controller -./build.sh 0.2.1 +./build.sh 0.2.11 # Build + push to Gitea registry -./build.sh 0.2.1 --push +./build.sh 0.2.11 --push ``` ### Deploy on customer node ```bash # Pull new image -docker pull gitea.dooplex.hu/admin/felhom-controller:0.2.1 +docker pull gitea.dooplex.hu/admin/felhom-controller:0.2.11 # IMPORTANT: use 'up -d', NOT 'restart' — restart doesn't pick up new images cd /opt/docker/felhom-controller @@ -342,7 +344,7 @@ docker compose up -d | Node | Hardware | Domain | IP | Status | |------|----------|--------|----|--------| -| demo-felhom | Acemagic GK3PLUS N100, 16G RAM, 512G SSD + 1TB HDD | demo-felhom.eu | 192.168.0.162 | ✅ Controller v0.2.1 + Paperless-ngx running | +| demo-felhom | Acemagic GK3PLUS N100, 16G RAM, 512G SSD + 1TB HDD | demo-felhom.eu | 192.168.0.162 | ✅ Controller v0.2.11 + Paperless-ngx running | | pi-customer-1 | Raspberry Pi 3B+, 1G RAM, 32G SD | pi-customer-1.local | — | 📲 Not yet tested | ### First deployment log (Paperless-ngx on demo-felhom) @@ -372,6 +374,7 @@ docker compose up -d | POST | `/api/stacks/{name}/stop` | Yes | Stop stack (not protected) | | POST | `/api/stacks/{name}/restart` | Yes | Restart stack | | POST | `/api/stacks/{name}/update` | Yes | Pull images + recreate | +| POST | `/api/stacks/{name}/optional-config` | Yes | Update optional config env vars | | GET | `/api/stacks/{name}/logs` | Yes | Container logs (add `?raw=1` for plain text) | | POST | `/api/stacks/rescan` | Yes | Trigger manual stack discovery | | GET | `/api/system/info` | Yes | System resource usage (RAM, disk, HDD) |