From a7a5304093fc1c1f5a49602c7d10bb0c58de330a Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Fri, 20 Feb 2026 16:07:13 +0100 Subject: [PATCH] docs: update Hub README.md with v0.2.1 features Document unified customer page, blocked status, pending dashboard, config push, auto-create config, and customer state matrix. Co-Authored-By: Claude Opus 4.6 --- hub/README.md | 79 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 24 deletions(-) diff --git a/hub/README.md b/hub/README.md index 4f3bded..e0cfd5e 100644 --- a/hub/README.md +++ b/hub/README.md @@ -4,7 +4,7 @@ A lightweight Go service that receives periodic reports from felhom-controller instances, stores them in SQLite, and provides a web dashboard for fleet monitoring. Also serves as the infrastructure backup store for disaster recovery. -**Current version: v0.2.0** +**Current version: v0.2.1** --- @@ -18,20 +18,22 @@ A lightweight Go service that receives periodic reports from felhom-controller i │ │ │ ┌─────────────────┐ │ │ POST /api/v1/ │ │ │ API Handler │ │ │ report │ │ │ (ingest reports, │ │ -│ infra-backup │ │ │ infra backups) │ │ -│ notify │ │ └────────┬────────┘ │ -│ │ │ │ │ -└─────────────────┘ │ ┌────────▼────────┐ │ - │ │ SQLite Store │ │ - Operator browser │ │ (reports, │ │ -┌─────────────────┐ │ │ infra_backups, │ │ -│ Web Dashboard │◀── HTML pages ──────│ │ notifications) │ │ -│ (hub.felhom.eu) │ (bcrypt auth) │ └─────────────────┘ │ -└─────────────────┘ │ │ +│ infra-backup │◀── config push ────│ │ infra backups, │ │ +│ notify │ (YAML body) │ │ config push) │ │ +│ │ │ └────────┬────────┘ │ +└─────────────────┘ │ │ │ + │ ┌────────▼────────┐ │ + Operator browser │ │ SQLite Store │ │ +┌─────────────────┐ │ │ (reports, │ │ +│ Web Dashboard │◀── HTML pages ──────│ │ infra_backups, │ │ +│ (hub.felhom.eu) │ (bcrypt auth) │ │ configs, │ │ +└─────────────────┘ │ │ notifications) │ │ + │ └─────────────────┘ │ + │ │ │ ┌─────────────────┐ │ │ │ Web Dashboard │ │ - │ │ (multi-customer │ │ - │ │ overview) │ │ + │ │ (unified customer│ │ + │ │ management) │ │ │ └─────────────────┘ │ └────────────────────────┘ ``` @@ -97,14 +99,43 @@ Config retrieval uses a separate per-customer retrieval password (not the API ke Protected by bcrypt password + session cookie (7-day expiry). -- **Customer overview table:** status indicators (OK/WARN/DOWN), CPU/memory %, disk usage, container counts, backup age, controller version -- **Customer detail page:** system info, storage bars, container table, notification preferences, notification log, 24h history graphs -- **Configurations page:** CRUD management for customer configs — pre-configure customer identity, infrastructure secrets, monitoring UUIDs; auto-generates retrieval password + per-customer API key; shows setup commands (`docker-setup.sh` and `curl`); YAML preview -- **Auto-refresh:** 60-second cycle -- **Status logic:** - - Green: report < 30 min old, health = ok - - Yellow: 30-60 min stale or health = warn - - Red: > 60 min stale or health = fail +### Pages + +- **Dashboard (`/`)** — Fleet overview table showing all customers with live status. Config-only customers (no reports yet) appear as "PENDING" with gray badge. Blocked customers are hidden. Auto-refreshes every 60 seconds. +- **Customers (`/configs`)** — Customer management list. Shows all customers (both managed and manual), their status, controller version, and config type (MANAGED/MANUAL). Blocked customers shown grayed-out with BLOCKED badge. +- **Unified Customer Detail (`/customers/{id}`)** — Single page per customer combining config management and live monitoring. Adapts content based on available data: + - **Managed + reporting:** Full view — config info, system metrics, storage, containers, backup status, credentials, setup commands, YAML preview, controller update, notifications, history + - **Managed + no reports yet:** Config info, credentials, setup commands, "Waiting for first report" indicator + - **Manual (report-only):** System metrics, storage, containers, backup, with "Create Config" button to convert to managed +- **Config Form (`/configs/new`, `/configs/{id}/edit`)** — Create/edit customer configurations with identity, infrastructure tokens, and monitoring overrides + +### Customer States + +| State | Dashboard | Customers List | Detail Page | +|-------|-----------|----------------|-------------| +| **Active + reporting** | Shown with live status | MANAGED + status badge | Full unified view | +| **Active + no reports** | Shown as PENDING (gray) | MANAGED + no status | Config + "waiting for report" | +| **Manual (report-only)** | Shown with live status | MANUAL + status badge | Reports + "Create Config" button | +| **Blocked** | Hidden | Shown grayed-out, BLOCKED badge | Blocked banner + Unblock button | + +### Customer Actions + +| Action | Description | +|--------|-------------| +| **Block/Unblock** | Toggle blocked status — blocked customers are hidden from dashboard and notifications are suppressed, but reports are still accepted and stored | +| **Push Config** | Generate YAML from Hub config and POST it to the controller's `/api/config/apply` endpoint (requires controller URL from reports) | +| **Create Config** | Auto-create a managed config from a manual customer's report data, then redirect to edit form | +| **Trigger Update** | Instruct controller to self-update to the latest version | +| **Delete** | Remove customer config (customer reappears as manual if reports continue) | + +### Status Logic + +- **OK (green):** report < 30 min old, health = ok +- **WARN (yellow):** 30-60 min stale or health = warn +- **DOWN (red):** > 60 min stale or health = fail +- **DISABLED (gray):** controller monitoring paused +- **PENDING (gray):** config exists but no reports received yet +- **BLOCKED (gray):** customer blocked by operator ## Data Storage @@ -116,7 +147,7 @@ SQLite with WAL mode. Tables: | `infra_backups` | Per-customer infrastructure snapshots for disaster recovery | | `customer_notifications` | Email + enabled event types per customer | | `notification_log` | Send/skip/fail history for notifications | -| `customer_configs` | Pre-configured customer settings, retrieval passwords, per-customer API keys | +| `customer_configs` | Pre-configured customer settings, retrieval passwords, per-customer API keys, status (active/blocked) | Retention: configurable (default 90 days), daily prune at 04:30 Budapest time. @@ -164,10 +195,10 @@ Runs on k3s (Kubernetes) in the `felhom-system` namespace: ```bash # Build and push cd hub/ -make VERSION=0.2.0 docker docker-push +make VERSION=0.2.1 docker docker-push # Deploy -kubectl set image -n felhom-system deploy/hub hub=gitea.dooplex.hu/admin/felhom-hub:v0.2.0 +kubectl set image -n felhom-system deploy/hub hub=gitea.dooplex.hu/admin/felhom-hub:v0.2.1 kubectl rollout status -n felhom-system deploy/hub # Check