diff --git a/CLAUDE.md b/CLAUDE.md index 3d00c86..e052736 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,44 @@ See `TASK.md` for the current task to implement (if it exists). Claude in Chrome extension is available — can be used to test web UI on demo-felhom.eu or verify dashboard deployments in browser. +## System context — the Proxmox re-platform (READ THIS FIRST) + +The project has **re-platformed onto Proxmox**, with a locked **three-component model**: +- **Hub** (`felhom.eu/hub/`) — operator backend on k3s. +- **Host agent** (`felhom-agent/`, formerly `proxmox-controller`) — one per Proxmox host; operator-tier; owns ALL Proxmox interaction. +- **In-guest controller** (THIS repo) — one per customer LXC; **Docker-only; holds NO Proxmox credentials**. + +**This repo is being de-privileged.** In the target model, host/disk/Proxmox/Cloudflare +responsibilities move OUT of the controller into the **host agent**: System info, Storage (disk +scan/format/mount/migrate), the disk-tier Backup (restic, cross-drive, drive-restore, infra-backup), +and the Cloudflare-API geo enforcement. The controller keeps the **app domain**: stack/deploy +management, the Hungarian web UI, app-data backup (DB dumps + Docker-volume tars), metrics/telemetry, +integrations, git-sync, notifications. + +> **Authoritative map:** `felhom.eu/documentation/architecture/02-controller-module-map.md` — the +> per-package **KEEP / PORT / DELETE(→agent) / DELETE(obsolete) / MODIFY** classification. Read it +> before touching `backup/`, `storage/`, `cloudflare/`, `system/`, or `config/`. Also doc 01 +> (topology/trust) and doc 03 (the host agent). + +**⚠️ Status — do NOT assume the target state is implemented.** The de-privileging has only *started*: +the recent `internal/appbackup/` extraction split the keep-side app-data-backup primitives from the +delete-side disk/host code (groundwork, no behaviour change). The **bulk strip has NOT happened** — +the current code STILL contains the full privileged storage / restic / cross-drive / disk / +Cloudflare stack. The strip + the agent-local-API client land at **~slice 8**. So the code you see +is the **pre-strip, still-privileged** controller; match the code, not the target, unless a TASK +says otherwise. + +**Don't confuse the two ex-"controllers":** `felhom-agent` (host, operator-tier, was +`proxmox-controller`) vs this `felhom-controller` (in-guest, was `deploy-felhom-compose`). + +## Cross-repo & artifacts + +- Workspace orientation (the felhom system, shared conventions, access) lives in the workspace-root + `e:\git\CLAUDE.md`. Sibling per-repo files: `felhom-agent/CLAUDE.md`, `felhom.eu/CLAUDE.md`. +- **Artifact taxonomy:** `TASK.md` / `TASK-*.md` = a spec for YOU to implement (then push + update + CHANGELOG + CONTEXT + README). +- **`RUNBOOK-*.md`** — an operational procedure. CC executes the steps it has access and capability for, including live validation on the demo nodes and the demo Proxmox host (CC has root@felhom-pve SSH + the felhom-agent token). A step is human-only only when it genuinely needs physical presence, a real-world decision, or credentials CC truly lacks — mark those steps HUMAN. Do not decline a whole procedure because it touches a live host or a privileged token. (Judgment still applies: confirm before irreversible ops on real customer data — but demo scratch guests are fair game.) + ## Code quality rules - Always double-check generated code for bugs, logic issues, syntax errors @@ -101,8 +139,7 @@ substitute the full path manually. | Host | OS | IP | User | Role | |------|----|----|------|------| | Build server | Debian 13 | 192.168.0.180 | kisfenyo | Build + push container images | -| Demo node | Debian 13 | 192.168.0.162 | kisfenyo | Test deployment (demo-felhom.eu) | -| Demo node 2 | Debian 13 | router.abonet.hu (SSH port 33022) | kisfenyo | Remote test deployment | +| Demo Proxmox host | 192.168.0.162 | root@pam (SSH alias felhom-pve, root, no sudo) | pveum/pct + live Proxmox validation — available to CC | ## Test environments @@ -115,6 +152,12 @@ substitute the full path manually. - Pi-hole DNS on local network forwards `*.demo-felhom.eu` → 192.168.0.162 - External access via Cloudflare Tunnel → Traefik reverse proxy +> **⚠️ Re-platform note:** per the host-agent work, `192.168.0.162` is now a **Proxmox host** +> (`demo-felhom`, PVE 9.2.2) — the demo-node tables above predate that. Confirm how/where the +> controller is currently deployed and tested post-re-platform before relying on the bare-metal +> `docker compose` deploy steps below; on the re-platformed node the controller may now run inside +> an LXC guest rather than directly on the host. + ## Build & deploy workflow — MANDATORY After making code changes to the controller, you **MUST** build, push, and deploy the new image.