From 136bdb563b933a63bb2a2dd4db9b559c37c22c76 Mon Sep 17 00:00:00 2001 From: oskar Date: Tue, 4 Aug 2026 15:07:09 +0200 Subject: [PATCH] feat(kb): SPLIT vps-control-plane -> subsystem (deprecated) + runbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit kb/subsystems/control-plane.md — status: deprecated, superseded_by: "przepisany tor redeploy, commity da151fc/79bfe8c 2026-08-03" kb/runbooks/control-plane-deploy-recovery.md — Deployment + Recovery Rozstrzygniecie 3: dokument NIE jest odswiezany, tylko oznaczony jako nieaktualny. Ostatnia zmiana tresci 2026-05-27, czyli przed przepisaniem toru redeployu. Co-Authored-By: Claude Opus 5 (1M context) --- kb/runbooks/control-plane-deploy-recovery.md | 60 +++++++++++++++++++ .../subsystems/control-plane.md | 59 ++++-------------- 2 files changed, 71 insertions(+), 48 deletions(-) create mode 100644 kb/runbooks/control-plane-deploy-recovery.md rename docs/vps-control-plane.md => kb/subsystems/control-plane.md (72%) diff --git a/kb/runbooks/control-plane-deploy-recovery.md b/kb/runbooks/control-plane-deploy-recovery.md new file mode 100644 index 0000000..c0faebe --- /dev/null +++ b/kb/runbooks/control-plane-deploy-recovery.md @@ -0,0 +1,60 @@ +--- +okf: "0.1" +type: runbook +visibility: private +status: active +updated: 2026-05-27 +links: + - ../subsystems/control-plane.md +--- + +# Control-plane — deployment i recovery + +## Deployment + +### From SATURN (primary control node) +```bash +# Full deploy via SSH +./scripts/deploy/deploy-control-plane.sh --ssh + +# Or manually: +ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws && git pull origin master && cd services/control-plane && docker compose up -d --build --force-recreate" +``` + +### Direct on VPS +```bash +cd ~/homelab-codex-ws/services/control-plane +docker compose up -d --build --force-recreate +``` + +`deploy-local.sh` also creates the required `/opt/homelab/` directory structure and sets ownership to UID 1000 (requires `sudo`). If directories already exist, skip to the `docker compose` step directly. + +### Verification +```bash +# On VPS +docker ps --filter "name=control-plane" +curl -s http://localhost:18180/summary | python3 -m json.tool +``` + +## Recovery + +### World state is stale or corrupt +```bash +# On VPS — delete checkpoint to force full replay +rm /opt/homelab/state/observer_checkpoint.json +docker restart control-plane-observer +``` + +### Flood of pending actions after bootstrap +Check if node-agent is running and emitting `service_healthy` events on each node. Without `service_healthy`, the supervisor sees all services as missing and queues redeployments every cycle. + +```bash +# Check node-agent on each node +ssh oskar@ "docker ps --filter name=node-agent && docker logs node-agent --tail 20" +``` + +### Rebuild from scratch +```bash +ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws/services/control-plane && docker compose up -d --build --force-recreate" +``` + diff --git a/docs/vps-control-plane.md b/kb/subsystems/control-plane.md similarity index 72% rename from docs/vps-control-plane.md rename to kb/subsystems/control-plane.md index 4caa252..e04a780 100644 --- a/docs/vps-control-plane.md +++ b/kb/subsystems/control-plane.md @@ -1,3 +1,14 @@ +--- +okf: "0.1" +type: subsystem +visibility: private +status: deprecated +updated: 2026-05-27 +links: + - ../runbooks/control-plane-deploy-recovery.md +superseded_by: "przepisany tor redeploy, commity da151fc/79bfe8c 2026-08-03" +--- + # VPS Control Plane The VPS Control Plane is the orchestration brain of the homelab platform. It runs on the Hetzner VPS (Tailscale IP: `100.95.58.48`) and provides observability, automated reconciliation, and a web-based operator interface. @@ -48,32 +59,6 @@ The supervisor supports a `NODE_ALIAS_MAP` environment variable (JSON string) to NODE_ALIAS_MAP='{"node-2": "chelsty-infra", "node-1": "piha"}' ``` -## Deployment - -### From SATURN (primary control node) -```bash -# Full deploy via SSH -./scripts/deploy/deploy-control-plane.sh --ssh - -# Or manually: -ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws && git pull origin master && cd services/control-plane && docker compose up -d --build --force-recreate" -``` - -### Direct on VPS -```bash -cd ~/homelab-codex-ws/services/control-plane -docker compose up -d --build --force-recreate -``` - -`deploy-local.sh` also creates the required `/opt/homelab/` directory structure and sets ownership to UID 1000 (requires `sudo`). If directories already exist, skip to the `docker compose` step directly. - -### Verification -```bash -# On VPS -docker ps --filter "name=control-plane" -curl -s http://localhost:18180/summary | python3 -m json.tool -``` - ## Action Approval Workflow ``` @@ -87,28 +72,6 @@ Supervisor writes → /opt/homelab/actions/pending/.json Possible action states: `pending → approved → running → completed / failed / rejected` Auto-cancel path: `pending → cancelled/` -## Recovery - -### World state is stale or corrupt -```bash -# On VPS — delete checkpoint to force full replay -rm /opt/homelab/state/observer_checkpoint.json -docker restart control-plane-observer -``` - -### Flood of pending actions after bootstrap -Check if node-agent is running and emitting `service_healthy` events on each node. Without `service_healthy`, the supervisor sees all services as missing and queues redeployments every cycle. - -```bash -# Check node-agent on each node -ssh oskar@ "docker ps --filter name=node-agent && docker logs node-agent --tail 20" -``` - -### Rebuild from scratch -```bash -ssh oskar@100.95.58.48 "cd ~/homelab-codex-ws/services/control-plane && docker compose up -d --build --force-recreate" -``` - ## Integration ### piha agent-system webui (port 18180 on piha)