admin/deploy-felhom-compose
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added memory and context

Browse Source
This commit is contained in:
authentik Default Admin
2026-02-14 08:00:06 +01:00
parent 4282b8d8cb
commit 5d9087dc2b
3 changed files with 289 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
controller/README.md
+82 -39
View File
@@ -6,6 +6,7 @@ Replaces Portainer + scattered systemd scripts with a single, lightweight contai
- Hungarian-language web dashboard for customers
- Docker Compose stack management (start/stop/update)
- Interactive first-deployment flow with auto-generated secrets
- Health-aware container state monitoring (starting/unhealthy/running)
- Backup orchestration (DB dumps + restic snapshots) — Phase 3
- System health monitoring with Healthchecks pings — Phase 2
- Git-based stack synchronization with update management — Phase 4
@@ -13,12 +14,33 @@ Replaces Portainer + scattered systemd scripts with a single, lightweight contai
## Current Status
**Phase 1 — Stack Manager + Deploy Flow: core features operational.**
**Phase 1 — Stack Manager + Deploy Flow: ✅ COMPLETE**
The controller is built, deployed, and running on the N100 test node (demo-felhom.eu).
The web dashboard is accessible, stack scanning works, and the deploy UI renders correctly.
First application (Paperless-ngx) successfully deployed end-to-end through the dashboard on 2026-02-13.
Next milestone: end-to-end test deploying a real app (e.g., Paperless-ngx) through the dashboard.
**Milestone achieved:** Full deploy cycle works — customer clicks "Telepítés", fills in fields,
controller generates secrets, saves app.yaml, runs `docker compose up -d`, and the app comes up
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**
### What works
- Dashboard with live container state (green/orange/yellow/red)
- Deploy form with password validation, auto-generation, and field locking
- Stack operations: start, stop, restart, update (pull + recreate)
- Log viewer for each stack
- Deploy page doubles as config viewer (read-only mode for deployed apps)
- Periodic stack rescanning (every 2 minutes)
- Manual rescan endpoint (`POST /api/stacks/rescan`)
- Alphabetically sorted stack display (consistent card ordering)
- Protected stacks (traefik, cloudflared, felhom-controller) can't be stopped
### Known issues / next priorities
- Cloudflare Tunnel + Traefik TLS: paperless.demo-felhom.eu works locally but shows "Not secure" (certificate chain not fully validated through tunnel)
- No undo/delete for deployed apps yet
- Dashboard theme doesn't yet match felhom.eu dark theme
## Architecture
@@ -87,11 +109,11 @@ controller/
|--------|------|--------|----------------|
| **Config** | `internal/config/` | ✅ Done | Load & validate controller.yaml, env overrides |
| **Stacks** | `internal/stacks/` | ✅ Done | Compose operations, scanning, metadata, deploy flow |
| **API** | `internal/api/` | ✅ Done | REST endpoints (stacks, deploy, system info, health) |
| **API** | `internal/api/` | ✅ Done | REST endpoints (stacks, deploy, rescan, system info, health) |
| **Web** | `internal/web/` | ✅ Done | Hungarian dashboard, auth, deploy pages, asset serving |
| **Backup** | `internal/backup/` | 🔲 Phase 3 | DB dumps, restic snapshots, restore |
| **Monitor** | `internal/monitor/` | 🔲 Phase 2 | Health checks, Healthchecks pings, system metrics |
| **Scheduler** | `internal/scheduler/` | 🔲 Phase 2 | Cron-like job runner for all periodic tasks |
| **Backup** | `internal/backup/` | 📲 Phase 3 | DB dumps, restic snapshots, restore |
| **Monitor** | `internal/monitor/` | 📲 Phase 2 | Health checks, Healthchecks pings, system metrics |
| **Scheduler** | `internal/scheduler/` | 📲 Phase 2 | Cron-like job runner for all periodic tasks |
## Stack Management
@@ -110,11 +132,29 @@ controller/
- **User input**: HDD path, admin password, language, etc.
- **"🎲 Generálás"** button next to password fields
3. Clicks "Telepítés" → controller:
- Generates all secrets
- Validates required fields (checks path exists, etc.)
- Validates all required fields (password fields must be explicitly filled or generated)
- Generates auto-secrets (DB passwords, hex keys)
- Saves `app.yaml` (env vars + locked fields list)
- Runs `docker compose up -d` with env vars injected
- Updates in-memory state immediately (no stale "Telepítés" button)
4. Post-deploy: locked fields (DB_PASSWORD, etc.) become read-only
5. "Részletek" button opens deploy page in read-only mode showing current config
### Container state display
The dashboard shows health-aware container states with distinct colors:
| State | Color | Label | Meaning |
|-------|-------|-------|---------|
| Running + healthy | 🟢 Green | "Fut" | All containers running and healthy |
| Running + health: starting | 🟠 Orange | "Indulás..." | Container up but healthcheck not yet passed |
| Running + unhealthy | 🟡 Yellow | "Nem egészséges" | Container running but healthcheck failing |
| Stopped/exited | 🔴 Red | "Leállítva" | All containers stopped |
| Restarting | 🟡 Yellow | "Újraindítás..." | Container in restart loop |
| Not deployed | ⚪ Gray | "Nincs telepítve" | Compose file exists but not yet deployed |
Action buttons adapt: "operational" states (running/starting/unhealthy/restarting) show restart/stop,
while stopped states show a start button.
### Update strategy (Phase 4)
@@ -152,13 +192,14 @@ Each deployed app gets an `app.yaml` in its stack directory:
# /opt/docker/stacks/paperless-ngx/app.yaml
# Auto-generated by felhom-controller — do not edit locked fields manually
deployed: true
deployed_at: "2026-02-13T14:30:00Z"
deployed_at: "2026-02-13T21:10:00Z"
env:
DOMAIN: "demo-felhom.eu"
DB_PASSWORD: "a7f2b9c1e4d..." # locked
PAPERLESS_SECRET_KEY: "8b3e..." # locked
PAPERLESS_ADMIN_USER: "admin" # editable
HDD_PATH: "/mnt/hdd_1" # locked
PAPERLESS_OCR_LANGUAGE: "hun+eng" # editable
HDD_PATH: "/mnt/hdd_placeholder" # locked
locked_fields:
- DB_PASSWORD
- PAPERLESS_SECRET_KEY
@@ -166,9 +207,6 @@ locked_fields:
- HDD_PATH
```
Fields are defined in each stack's `.felhom.yml` metadata file. See
`configs/example-felhom-metadata.yml` for the full format.
### App assets (logos, screenshots)
Baked into the container image at build time — no external dependencies at runtime.
@@ -176,12 +214,6 @@ Synced from the felhom.eu website repo before building.
Served locally at `/static/assets/`. Logos try SVG first, fall back to PNG.
| Asset | File pattern | Served at |
|-------|-------------|-----------|
| Logo (SVG) | `assets/{slug}-logo.svg` | `/static/assets/{slug}-logo.svg` |
| Logo (PNG fallback) | `assets/{slug}-logo.png` | `/static/assets/{slug}-logo.png` |
| Screenshot | `assets/{slug}-screenshot-{n}.webp` | `/static/assets/{slug}-screenshot-{n}.webp` |
## Build & Deploy
Source: `https://gitea.dooplex.hu/admin/deploy-felhom-compose` → `controller/` subfolder.
@@ -192,27 +224,20 @@ See `docs/BUILDING.md` for the full guide.
```bash
# Quick build (current platform only)
cd ~/build/felhom-controller
./build.sh 0.1.0
./build.sh 0.2.1
# Build + push to Gitea registry
./build.sh 0.1.0 --push
# Build for N100 (amd64) + Pi (arm64) and push
./build.sh 0.1.0 --multiarch
./build.sh 0.2.1 --push
```
### Deploy on customer node
```bash
# Create config first
nano /opt/docker/felhom-controller/controller.yaml
# Pull new image
docker pull gitea.dooplex.hu/admin/felhom-controller:0.2.1
# Create .env for compose labels
echo "DOMAIN=demo-felhom.eu" > /opt/docker/felhom-controller/.env
# Pull and start
# IMPORTANT: use 'up -d', NOT 'restart' — restart doesn't pick up new images
cd /opt/docker/felhom-controller
docker compose pull
docker compose up -d
```
@@ -220,8 +245,22 @@ 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 running |
| pi-customer-1 | Raspberry Pi 3B+, 1G RAM, 32G SD | pi-customer-1.local | — | 🔲 Not yet tested |
| 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 |
| 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)
- **Date:** 2026-02-13
- **App:** Paperless-ngx (document management)
- **Deploy method:** Dashboard UI → "Telepítés" button
- **Issues encountered & resolved:**
1. Password fields accepted empty values → Added server-side + client-side validation
2. "Telepítés" button appeared for already-deployed apps → Fixed in-memory Deployed flag update
3. Green status shown for `(health: starting)` containers → Added health-aware state parsing
4. Stack cards switched positions on refresh → Added alphabetical sorting in GetStacks()
5. "Részletek" button did nothing for deployed apps → Redirects to deploy page (read-only)
6. OCR crash: `PAPERLESS_OCR_LANGUAGE=hun` not installed → Added `PAPERLESS_OCR_LANGUAGES` (plural) to docker-compose
7. Container restart vs recreate: `docker compose restart` doesn't pick up new images → Documented: always use `docker compose up -d`
## REST API
@@ -237,11 +276,12 @@ docker compose up -d
| POST | `/api/stacks/{name}/restart` | Yes | Restart stack |
| POST | `/api/stacks/{name}/update` | Yes | Pull images + recreate |
| GET | `/api/stacks/{name}/logs` | Yes | Container logs |
| POST | `/api/stacks/rescan` | Yes | Trigger manual stack discovery |
| GET | `/api/system/info` | Yes | Customer/domain info |
## Status & Roadmap
### Phase 1 — Stack Manager + Deploy Flow ✅
### Phase 1 — Stack Manager + Deploy Flow ✅ COMPLETE
- [x] Project skeleton & config format
- [x] .felhom.yml app metadata format with deploy fields
- [x] Per-app config persistence (app.yaml)
@@ -249,23 +289,26 @@ docker compose up -d
- [x] Stack catalog (read compose files + metadata from disk)
- [x] Docker Compose operations (up/down/pull/ps/logs)
- [x] Deploy flow with interactive field input
- [x] Password validation (server-side + client-side, no empty passwords)
- [x] Basic web dashboard with start/stop/deploy buttons
- [x] Health-aware container states (starting/unhealthy/running)
- [x] REST API for stack + deploy operations
- [x] Simple web authentication (bcrypt sessions)
- [x] App assets baked into container (SVG/PNG logos, webp screenshots)
- [x] Container image build pipeline (Dockerfile + build.sh)
- [x] Build + push to Gitea container registry
- [x] Deploy on N100 test node — dashboard accessible
- [x] Stack scanning + display working (whoami test stack)
- [ ] End-to-end test: deploy an app through dashboard (whoami / paperless-ngx)
- [ ] Dashboard UI redesign (align with felhom.eu dark theme)
- [x] Stack scanning + display working
- [x] **First app deployed: Paperless-ngx via dashboard** (2026-02-13)
- [x] Periodic stack rescanning (every 2 minutes)
- [x] Alphabetically sorted stack display
- [x] Deploy page doubles as read-only config viewer for deployed apps
### Phase 2 — Monitoring & Health
- [ ] System metrics collection (CPU, RAM, disk, temperature)
- [ ] Healthchecks.io ping integration
- [ ] Dashboard system health panel
- [ ] Customer notifications (email/Telegram)
- [ ] Periodic stack status refresh (background goroutine)
### Phase 3 — Backups
- [ ] DB dump engine (PostgreSQL, MariaDB/MySQL, SQLite)