From da991fad57ebaba0c3f52f866eb2a2f4b19aca60 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 21 Feb 2026 15:45:44 +0100 Subject: [PATCH] updated readme --- hub/README.md | 70 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 55 insertions(+), 15 deletions(-) diff --git a/hub/README.md b/hub/README.md index b60df8c..edf44cd 100644 --- a/hub/README.md +++ b/hub/README.md @@ -4,7 +4,7 @@ A lightweight Go service that receives periodic reports and structured events 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, event-based dead man's switch monitoring, and notification dispatch. -**Current version: v0.3.5** +**Current version: v0.3.7** --- @@ -19,15 +19,24 @@ A lightweight Go service that receives periodic reports and structured events fr │ POST /api/v1/ │ │ │ API Handler │ │ │ report │ │ │ (ingest reports, │ │ │ infra-backup │◀── config push ────│ │ infra backups, │ │ -│ notify │ (YAML body) │ │ config push) │ │ -│ │ │ └────────┬────────┘ │ -└─────────────────┘ │ │ │ - │ ┌────────▼────────┐ │ - Operator browser │ │ SQLite Store │ │ -┌─────────────────┐ │ │ (reports, │ │ +│ notify │ (YAML body) │ │ config push, │ │ +│ │ │ │ asset serving) │ │ +│ GET /api/v1/ │ │ └────────┬────────┘ │ +│ assets/* │◀── asset download ─│ │ │ +└─────────────────┘ (Bearer auth) │ ┌────────▼────────┐ │ + │ │ SQLite Store │ │ + Operator browser │ │ (reports, │ │ +┌─────────────────┐ │ │ assets, │ │ │ Web Dashboard │◀── HTML pages ──────│ │ infra_backups, │ │ │ (hub.felhom.eu) │ (bcrypt auth) │ │ configs, │ │ └─────────────────┘ │ │ notifications) │ │ + │ └─────────────────┘ │ + │ │ + │ ┌─────────────────┐ │ + │ │ Asset Manager │ │ + │ │ (PVC storage, │ │ + │ │ SHA-256 manifest│ │ + │ │ file serving) │ │ │ └─────────────────┘ │ │ │ │ ┌─────────────────┐ │ @@ -124,7 +133,20 @@ Notifications are dispatched automatically when events are processed: |--------|------|-------------| | `GET` | `/api/v1/config/{customer_id}` | Download generated controller.yaml (auth: `X-Retrieval-Password` header) | -Config retrieval uses a separate per-customer retrieval password (not the API key). The Hub generates a complete `controller.yaml` by deep-merging `controller.yaml.example` (periodically fetched from the Gitea repo) with customer-specific overrides (identity, infrastructure tokens, hub API key, session secret). +Config retrieval uses a separate per-customer retrieval password (not the API key). Retrieval passwords are auto-generated as **Hungarian word passphrases** (e.g., `alma-kerék-madár-felhő`) for easy phone-based entry during disaster recovery. The Hub generates a complete `controller.yaml` by deep-merging `controller.yaml.example` (periodically fetched from the Gitea repo) with customer-specific overrides (identity, infrastructure tokens, hub API key, session secret). + +### Assets + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/v1/assets/manifest` | JSON manifest of all assets with SHA-256 checksums | +| `GET` | `/api/v1/assets/file/{filename}` | Download a single asset file (logo, screenshot) | + +Assets are stored on the Hub PVC at `/assets/`. On first run, assets are seeded from the Docker image (`/usr/share/felhom/assets-seed/`). The manifest includes filename, size, and SHA-256 hash for each file — controllers use this for efficient change detection. + +**Asset types served:** `{slug}-logo.svg`, `{slug}-logo.png`, `{slug}-screenshot-{N}.webp` + +The asset manager (`internal/assets/`) scans the assets directory on startup, builds an in-memory manifest, and serves files with appropriate Content-Type and cache headers. Both endpoints require Bearer token auth (global or per-customer API key). ### Health @@ -191,6 +213,10 @@ SQLite with WAL mode. Tables: Retention: configurable (default 90 days), daily prune at 04:30 Budapest time. +### PVC Asset Storage + +App assets (logos, screenshots) are stored on the PVC at `/assets/`. On first run (empty directory), assets are seeded from `/usr/share/felhom/assets-seed/` (baked into the Docker image during build). This means assets survive container rebuilds but fresh deploys get a full set from the image seed. + ## Configuration ```yaml @@ -229,24 +255,28 @@ server: ## Deployment Runs on k3s (Kubernetes) in the `felhom-system` namespace: -- **PVC:** 1GB Longhorn volume for SQLite database +- **PVC:** 1GB Longhorn volume for SQLite database + app assets - **Resources:** 64Mi-256Mi memory, 50m-500m CPU - **Ingress:** `hub.felhom.eu` with TLS (cert-manager) - **Geo-restriction:** Hungary only (nginx annotation) ```bash -# Build and push -cd hub/ -make VERSION=0.3.0 docker docker-push +# Build and push (on 192.168.0.180) +cd ~/build/felhom-hub +./build.sh v0.3.7 --push +# Build script auto-syncs app assets from website/assets/ into the image -# Deploy -kubectl set image -n felhom-system deploy/hub hub=gitea.dooplex.hu/admin/felhom-hub:v0.3.0 -kubectl rollout status -n felhom-system deploy/hub +# Deploy (ArgoCD managed — update manifests/hub.yaml image tag, commit+push) +git pull && kubectl apply -f manifests/hub.yaml # Check kubectl logs -n felhom-system -l app=hub --tail 20 ``` +**Note:** `kubectl set image` alone does NOT persist — ArgoCD reverts it. Always update `manifests/hub.yaml` and apply. + +The Dockerfile includes `COPY assets/ /usr/share/felhom/assets-seed/` which bakes app assets into the image as a seed for the PVC. The build script copies `*-logo.svg`, `*-logo.png`, and `*-screenshot-*.webp` from the website repo's `assets/` directory. + ## Background Services | Service | Schedule | Description | @@ -256,6 +286,16 @@ kubectl logs -n felhom-system -l app=hub --tail 20 | **Report/event prune** | Daily 04:30 Budapest | Deletes reports and events older than retention period (default 90 days) | | **Registry version check** | Every 30min | Checks Gitea registry for new controller image tags | | **Template refresh** | Every 1h | Fetches latest `controller.yaml.example` from Gitea | +| **Asset seeding** | On startup | Seeds PVC assets from Docker image if `/assets/` is empty | + +## Internal Packages + +| Package | Purpose | +|---------|---------| +| `internal/api` | REST API handler (report ingest, config, events, assets, notifications) | +| `internal/web` | Web dashboard (session auth, customer management, fleet overview) | +| `internal/assets` | PVC asset manager (manifest generation, SHA-256 checksums, file serving, image seed) | +| `internal/configgen` | Shared YAML config generation (deep-merge template + customer overrides) | ## Dependencies