updated readme
This commit is contained in:
+55
-15
@@ -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 `<dataDir>/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 `<dataDir>/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 `<dataDir>/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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user