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

docs: reflow CLAUDE.md; unify REPORT/CHANGELOG convention; add no-secrets rule

Browse Source 
Reflow removes hard mid-paragraph line wraps (code blocks and tables untouched);
rendered output unchanged. Adds the uniform CHANGELOG (cumulative) / REPORT
(overwrite-latest) convention plus a no-secrets rule. Docs/meta only, no version bump.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
authentik Default Admin
2026-06-08 20:54:45 +02:00
parent 27c945d698
commit 086281b582
2 changed files with 28 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+6
View File
@@ -1,5 +1,11 @@
## Changelog
### docs: reflow CLAUDE.md; unify REPORT/CHANGELOG convention; add no-secrets rule (2026-06-08)
#### Changed
- **Reflowed `CLAUDE.md`** — removed hard mid-paragraph line wraps (prose, list items, blockquotes now single-line, soft-wrapped); code blocks and tables untouched; rendered output unchanged.
- **Added the uniform REPORT/CHANGELOG convention**: `CHANGELOG.md` is the cumulative log (newest on top); `REPORT.md` is overwritten with the most-recent implementation only. Added an explicit **no-secrets** rule (never write tokens/passwords/keys into committed files; reference them as stored out-of-band). Docs/meta only — no code change, no version bump.
### Repo rename — `deploy-felhom-compose` → `felhom-controller` (2026-06-08)
#### Changed
CLAUDE.md
+22 -51
View File
@@ -1,19 +1,14 @@
# CLAUDE.md — Project Instructions for Claude Code
> This file is read automatically by Claude Code at the start of every session.
> It replaces the "Instructions" panel from the claude.ai Project.
> Keep it updated as the project evolves.
> This file is read automatically by Claude Code at the start of every session. It replaces the "Instructions" panel from the claude.ai Project. Keep it updated as the project evolves.
!!! IMPORTANT !!!
- Always update CHANGELOG.md whenever you modified the code, and pushed to git!!
- IF controller feature changed (new/modify/remove) always update the relevant part of controller/README.md with the architectural change!!
## Project overview
Creating a business (Felhom) for home-server deployment for Hungarian customers. This repository
(`felhom-controller`) contains the felhom-controller — a Go application that manages Docker
Compose stacks on customer hardware via a Hungarian-language web dashboard.
Creating a business (Felhom) for home-server deployment for Hungarian customers. This repository (`felhom-controller`) contains the felhom-controller — a Go application that manages Docker Compose stacks on customer hardware via a Hungarian-language web dashboard.
See `controller/README.md` for full architecture and status (update after each session, keep track of how different functions/features operate, like backup, monitoring, storage handling, app management, user settings, update workflow, notification system, etc-etc...).
See `CHANGELOG.md` for recent work (update after each session — see "Working with CHANGELOG.md" below).
@@ -29,37 +24,26 @@ The project has **re-platformed onto Proxmox**, with a locked **three-component
- **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.
**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).
> **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.
**⚠️ 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`).
**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).
- 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.)
> **In every repository where you make a change, update both files in that repo:**
> - **`CHANGELOG.md`** — a cumulative log of **all** changes; newest entry on top.
> - **`REPORT.md`** — **overwrite** with a summary of the **most recent** implementation (or significant validation/operational run) only; not cumulative.
>
> **Never write secrets** — tokens, passwords, private keys, API keys — into `CHANGELOG.md`, `REPORT.md`, or any committed file. Reference them as "stored out-of-band" instead.
## Code quality rules
- Always double-check generated code for bugs, logic issues, syntax errors
@@ -78,8 +62,7 @@ says otherwise.
## Workspace layout
Claude Code runs on Windows 11. The working directory is `E:\git\` (mapped as `/e/git/` in Git Bash).
This repo is at:
Claude Code runs on Windows 11. The working directory is `E:\git\` (mapped as `/e/git/` in Git Bash). This repo is at:
```
E:\git\felhom-controller\ (or /e/git/felhom-controller/ in Git Bash)
@@ -124,17 +107,13 @@ All repos hosted at `gitea.dooplex.hu/admin/`. Git credentials are stored (`git
SSH key-based authentication is configured and working. No password prompts.
**IMPORTANT — SSH binary:** Claude Code runs in Git Bash, which has its own SSH at
`/usr/bin/ssh` (= `C:\Program Files\Git\usr\bin\ssh.exe`). This binary does NOT have
access to the Windows SSH agent and will fail silently (exit 0/141 with no output).
Always use the Windows native OpenSSH binary with the full path:
**IMPORTANT — SSH binary:** Claude Code runs in Git Bash, which has its own SSH at `/usr/bin/ssh` (= `C:\Program Files\Git\usr\bin\ssh.exe`). This binary does NOT have access to the Windows SSH agent and will fail silently (exit 0/141 with no output). Always use the Windows native OpenSSH binary with the full path:
```
SSH=/c/Windows/System32/OpenSSH/ssh.exe
```
All SSH commands in this file use `$SSH` — set it at the start of your session or
substitute the full path manually.
All SSH commands in this file use `$SSH` — set it at the start of your session or substitute the full path manually.
| Host | OS | IP | User | Role |
|------|----|----|------|------|
@@ -152,16 +131,11 @@ 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.
> **⚠️ 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.
Do NOT leave code changes uncommitted or undeployed. The full cycle is:
After making code changes to the controller, you **MUST** build, push, and deploy the new image. Do NOT leave code changes uncommitted or undeployed. The full cycle is:
### Step 1: Commit and push changes
@@ -186,8 +160,7 @@ Check the current running version:
$SSH kisfenyo@192.168.0.162 "docker ps --filter name=felhom-controller --format '{{.Image}}'"
```
Then build with the next version (e.g., if current is 0.2.10, use 0.2.11):
IMPORTANT!: Build directory is: ~/build/felhom-controller
Then build with the next version (e.g., if current is 0.2.10, use 0.2.11): IMPORTANT!: Build directory is: ~/build/felhom-controller
```bash
$SSH kisfenyo@192.168.0.180 "cd ~/build/felhom-controller && git -C ~/git/felhom-controller pull && ./build.sh <NEW_VERSION> --push"
```
@@ -234,8 +207,7 @@ $SSH -p 33022 kisfenyo@router.abonet.hu "docker logs felhom-controller --tail 20
### Build & deploy workflow — Hub (felhom-hub)
The central hub (`hub.felhom.eu`) is a separate Go app in the `E:\git\felhom.eu\hub\` repo.
The controller pushes periodic reports to it (when `hub.enabled: true` in `controller.yaml`).
The central hub (`hub.felhom.eu`) is a separate Go app in the `E:\git\felhom.eu\hub\` repo. The controller pushes periodic reports to it (when `hub.enabled: true` in `controller.yaml`).
| Step | Command | Where |
|------|---------|-------|
@@ -251,8 +223,7 @@ See `E:\git\felhom.eu\CLAUDE.md` for full hub details.
cd /e/git/app-catalog-felhom.eu
git add -A && git commit -m "<message>" && git push
```
The controller's git sync will pick up catalog changes within 15 minutes, or you can trigger it
manually via the dashboard "Sablonok frissítése" button.
The controller's git sync will pick up catalog changes within 15 minutes, or you can trigger it manually via the dashboard "Sablonok frissítése" button.
## Tech stack