From 29b2b8ad7cf9c938bb0b006b191b9b5dbc78b551 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sun, 19 Jul 2026 12:27:44 +0200 Subject: [PATCH] docs: DooPlex-local commands in PROMPT-TEMPLATE and the manual-build runbook --- documentation/PROMPT-TEMPLATE.md | 28 +++++++----- .../runbooks/RUNBOOK-manual-build.md | 43 ++++++++++--------- 2 files changed, 39 insertions(+), 32 deletions(-) diff --git a/documentation/PROMPT-TEMPLATE.md b/documentation/PROMPT-TEMPLATE.md index dce286a..6a68c7f 100644 --- a/documentation/PROMPT-TEMPLATE.md +++ b/documentation/PROMPT-TEMPLATE.md @@ -94,7 +94,8 @@ never park it on a branch. -1. `e:\git\CLAUDE.md` — workspace orientation (the felhom system, shared conventions, access). +1. `/mnt/5_hdd/felhom.eu/git/CLAUDE.md` — workspace orientation (the felhom system, shared + conventions, access). Versioned copy: `felhom.eu/documentation/runbooks/workspace-CLAUDE.md`. 2. `/CLAUDE.md` — repo build/deploy, code-quality rules, trunk-based + live-validation rules. 3. `/CONTEXT.md` — current project state / decisions / roadmap. 4. `felhom.eu/documentation/architecture/02-controller-module-map.md` — KEEP/PORT/DELETE/MODIFY @@ -332,28 +333,33 @@ status), update in the SAME session: ## 13. Build / deploy / STOP - + -**Controller** (build server `192.168.0.180` → guest via golden/bootstrap): +**Clean-tree gate first:** `git status --porcelain` empty AND `HEAD` == `origin/main` in the repo +being built. An unpushed change does not exist. + +**Controller** (local build on DooPlex → guest via golden/bootstrap): ```bash -SSH=/c/Windows/System32/OpenSSH/ssh.exe +FELHOM_ROOT=/mnt/5_hdd/felhom.eu # build + push -$SSH kisfenyo@192.168.0.180 "cd ~/build/felhom-controller && git -C ~/git/felhom-controller pull && ./build.sh --push" +cd $FELHOM_ROOT/build/felhom-controller && git -C $FELHOM_ROOT/git/felhom-controller pull && ./build.sh --push # deploy to guest (golden/bootstrap): docker pull → write /etc/felhom-controller-image → restart bootstrap svc # verify: -$SSH kisfenyo@ "docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}' && docker logs felhom-controller --tail 20" +ssh felhom-pve "pct exec 9201 -- docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}'" ``` -**Agent** (build + push `felhom-agent:`; deploy to `felhom-pve`: backup prior binary, replace, -restart service; verify clean restart — e.g. `ReassertGuestBinds` does not rebind a non-`enrolled` drive). +**Agent** (build locally, `scp /tmp/felhom-agent- felhom-pve:/tmp/` — one hop; deploy to +`felhom-pve`: backup prior binary, replace, restart service; verify clean restart — e.g. +`ReassertGuestBinds` does not rebind a non-`enrolled` drive). -**Hub** (`felhom.eu/hub/`): build + push, then -`$SSH kisfenyo@192.168.0.180 "sudo kubectl set image -n felhom-system deploy/hub hub=...:"` + verify pods/logs. +**Hub** (`felhom.eu/hub/`): build + push locally, then bump `manifests/hub.yaml`'s `image:` tag in +git and do a deliberate ArgoCD sync — **never `kubectl set image`** (auto-sync is OFF and any +imperative change is reverted on the next sync). Verify Synced/Healthy + rollout + image + logs. **Live validation rule:** if validating a user-facing feature, exercise the **real server pipeline** (connect → enroll → deploy), or invoke the **exact endpoint the UI invokes** (acceptable proxy — no server logic skipped). **Do NOT** hand-set state via raw agent attach (the F9 bypass). Browser -automation (`claude-in-chrome`) is available for true UI coverage — say which method was used. +automation is **NOT available** on DooPlex — endpoint-level is the standard method; say which was used. **STOP point (risky/supervised tasks):** build + unit-test + build/deploy images, but **do NOT run a live destructive op or migrate real customer data** — that is the supervised [Bx] step. Throwaway diff --git a/documentation/runbooks/RUNBOOK-manual-build.md b/documentation/runbooks/RUNBOOK-manual-build.md index 95aa7fb..3a7d551 100644 --- a/documentation/runbooks/RUNBOOK-manual-build.md +++ b/documentation/runbooks/RUNBOOK-manual-build.md @@ -1,6 +1,7 @@ # RUNBOOK — manual build / deploy / publish (agent · controller · golden · hub) -**Audience:** the operator, from the Windows workstation (Git Bash), same environment CC uses. +**Audience:** the operator, on DooPlex (192.168.0.180, Debian 13) — the same environment CC uses. +Builds are local commands; felhom-pve is one `ssh` hop. **Written:** 2026-07-11, from the verified `felhom.eu/skills/felhom-build-deploy/SKILL.md` command set + the publish-train procedure (`documentation/pilot/RUNBOOK-publish-0.79-0.110-2026-07-10.md`) + `documentation/runbooks/publish-train-rules.md`. If this doc and the skill ever disagree, the skill wins. @@ -28,15 +29,16 @@ acts immediately; save it LAST). Rules: `publish-train-rules.md`. ## 1. Session setup (every session, first) ```bash -SSH=/c/Windows/System32/OpenSSH/ssh.exe # Git Bash's own ssh fails silently against the Windows agent -export MSYS_NO_PATHCONV=1 # before any felhom-pve command with absolute paths (pct etc.) -FELHOM_ROOT=/mnt/5_hdd/felhom.eu # build-server working root: ALL felhom repos/build/drill/iso moved HERE 2026-07-18 +FELHOM_ROOT=/mnt/5_hdd/felhom.eu # working root: ALL felhom repos/build/drill/iso live HERE ``` +**Clean-tree gate before any build:** `git status --porcelain` must be empty and `git rev-parse HEAD` +must equal `git rev-parse origin/main` in the repo being built. An unpushed change does not exist. + | Host | Access | Role | |---|---|---| -| Build server | `$SSH kisfenyo@192.168.0.180` | builds (`$FELHOM_ROOT/git/felhom-agent`, `$FELHOM_ROOT/build/felhom-controller`, `$FELHOM_ROOT/build/felhom-hub`), kubectl | -| Demo PVE host | `$SSH felhom-pve` (root@192.168.0.162) | agent install, `pct exec 9201` | +| DooPlex (this host) | local | builds (`$FELHOM_ROOT/git/felhom-agent`, `$FELHOM_ROOT/build/felhom-controller`, `$FELHOM_ROOT/build/felhom-hub`), kubectl | +| Demo PVE host | `ssh felhom-pve` (root@192.168.0.162) | agent install, `pct exec 9201` | | Hub UI | hub.felhom.eu → Configuration | manifest vouch, MinAgent, floor (operator password) | Housekeeping note: `$FELHOM_ROOT/build/felhom-agent` on 180 is a stale pre-June-23 leftover — agent @@ -48,14 +50,13 @@ Always commit+push to `main` first (an unpushed change does not exist). ```bash # BUILD on 180 (the explicit git pull is load-bearing) -$SSH kisfenyo@192.168.0.180 "cd $FELHOM_ROOT/git/felhom-agent && git pull && go build -ldflags '-X main.version=' -o /tmp/felhom-agent- ./cmd/felhom-agent" +cd $FELHOM_ROOT/git/felhom-agent && git pull && go build -ldflags '-X main.version=' -o /tmp/felhom-agent- ./cmd/felhom-agent -# FETCH locally, PUSH to the PVE host (Windows scp needs cygpath for the local side) -scp kisfenyo@192.168.0.180:/tmp/felhom-agent- "$(cygpath -w /tmp/felhom-agent-)" -scp "$(cygpath -w /tmp/felhom-agent-)" felhom-pve:/tmp/ +# PUSH to the PVE host — ONE hop, the binary is already local +scp /tmp/felhom-agent- felhom-pve:/tmp/ # DEPLOY with backup + restart + verify -$SSH felhom-pve "cp /usr/local/bin/felhom-agent /usr/local/bin/felhom-agent.bak-\$(/usr/local/bin/felhom-agent --version | awk '{print \$2}') && install -m0755 /tmp/felhom-agent- /usr/local/bin/felhom-agent && systemctl restart felhom-agent && sleep 3 && /usr/local/bin/felhom-agent --version && journalctl -u felhom-agent -n 20 --no-pager" +ssh felhom-pve "cp /usr/local/bin/felhom-agent /usr/local/bin/felhom-agent.bak-\$(/usr/local/bin/felhom-agent --version | awk '{print \$2}') && install -m0755 /tmp/felhom-agent- /usr/local/bin/felhom-agent && systemctl restart felhom-agent && sleep 3 && /usr/local/bin/felhom-agent --version && journalctl -u felhom-agent -n 20 --no-pager" ``` Gotchas (earned): if `configs/` changed in the repo, ship the **sudoers + guarded wrapper WITH the @@ -83,13 +84,13 @@ artifact manifest**. (This save does NOT move the floor — that's a separate ca ```bash # BUILD+PUSH the image (build.sh does NOT pull — the explicit pull is load-bearing) -$SSH kisfenyo@192.168.0.180 "cd $FELHOM_ROOT/build/felhom-controller && git -C $FELHOM_ROOT/git/felhom-controller pull && ./build.sh --push" +cd $FELHOM_ROOT/build/felhom-controller && git -C $FELHOM_ROOT/git/felhom-controller pull && ./build.sh --push # DEPLOY on the demo guest -$SSH felhom-pve "pct exec 9201 -- bash -c 'docker pull gitea.dooplex.hu/admin/felhom-controller: && echo gitea.dooplex.hu/admin/felhom-controller: > /etc/felhom-controller-image && systemctl restart felhom-controller-bootstrap.service'" +ssh felhom-pve "pct exec 9201 -- bash -c 'docker pull gitea.dooplex.hu/admin/felhom-controller: && echo gitea.dooplex.hu/admin/felhom-controller: > /etc/felhom-controller-image && systemctl restart felhom-controller-bootstrap.service'" # VERIFY -$SSH felhom-pve "pct exec 9201 -- docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}'" +ssh felhom-pve "pct exec 9201 -- docker ps --filter name=felhom-controller --format '{{.Image}} {{.Status}}'" ``` **Remote rollout** = the hub floor (Configuration → Managed updates). Order rules (train rules doc): @@ -120,20 +121,20 @@ tag changes in git and the ArgoCD app is deliberately synced (auto-sync is OFF; `kubectl set image`, never `:latest`). ```bash -$SSH kisfenyo@192.168.0.180 "cd $FELHOM_ROOT/build/felhom-hub && ./build.sh --push" +cd $FELHOM_ROOT/build/felhom-hub && ./build.sh --push # edit manifests/hub.yaml image tag → ; commit; push -$SSH kisfenyo@192.168.0.180 "sudo kubectl -n argocd annotate application felhom argocd.argoproj.io/refresh=hard --overwrite; sleep 8; sudo kubectl -n argocd get application felhom -o jsonpath='{.status.sync.status} {.status.sync.revision}{\"\n\"}'" -$SSH kisfenyo@192.168.0.180 "sudo kubectl -n argocd patch application felhom --type merge -p '{\"operation\":{\"initiatedBy\":{\"username\":\"op\"},\"sync\":{\"syncStrategy\":{\"apply\":{}}}}}'" +sudo kubectl -n argocd annotate application felhom argocd.argoproj.io/refresh=hard --overwrite; sleep 8; sudo kubectl -n argocd get application felhom -o jsonpath='{.status.sync.status} {.status.sync.revision}{"\n"}' +sudo kubectl -n argocd patch application felhom --type merge -p '{"operation":{"initiatedBy":{"username":"op"},"sync":{"syncStrategy":{"apply":{}}}}}' # verify: Synced/Healthy + rollout + live image tag + logs -$SSH kisfenyo@192.168.0.180 "sudo kubectl -n argocd get application felhom -o jsonpath='sync={.status.sync.status} health={.status.health.status}{\"\n\"}'; sudo kubectl -n felhom-system rollout status deploy/hub --timeout=90s; sudo kubectl -n felhom-system get deploy hub -o jsonpath='{.spec.template.spec.containers[0].image}'; echo; sudo kubectl -n felhom-system logs -l app=hub --tail 10" +sudo kubectl -n argocd get application felhom -o jsonpath='sync={.status.sync.status} health={.status.health.status}{"\n"}'; sudo kubectl -n felhom-system rollout status deploy/hub --timeout=90s; sudo kubectl -n felhom-system get deploy hub -o jsonpath='{.spec.template.spec.containers[0].image}'; echo; sudo kubectl -n felhom-system logs -l app=hub --tail 10 ``` ## 6. "What's live right now?" one-liners ```bash -$SSH felhom-pve "/usr/local/bin/felhom-agent --version" # agent on demo -$SSH felhom-pve "pct exec 9201 -- cat /etc/felhom-controller-image" # controller on demo -$SSH kisfenyo@192.168.0.180 "sudo kubectl -n felhom-system get deploy hub -o jsonpath='{.spec.template.spec.containers[0].image}'" # hub +ssh felhom-pve "/usr/local/bin/felhom-agent --version" # agent on demo +ssh felhom-pve "pct exec 9201 -- cat /etc/felhom-controller-image" # controller on demo +sudo kubectl -n felhom-system get deploy hub -o jsonpath='{.spec.template.spec.containers[0].image}' # hub # published = the hub Configuration dropdowns (they read Gitea packages live) # fleet = hub Dashboard per-host rows (agent_version + controller version per box) ```