6dffa5c565
126 plikow (md, yaml, sh, py) odwolywalo sie do sciezek sprzed migracji.
15 markdown-linkow [..](..) -> policzona sciezka WZGLEDNA wobec pliku
odsylajacego (wczesniej czesc z nich byla repo-root-relative i nie
rozwiazywala sie z katalogu, w ktorym lezala)
200 odwolan tekstowych (backticki, proza, yaml, importy w kodzie)
-> nowa sciezka repo-root-relative, zgodnie z konwencja repo
5 linkow rodzenstwa (gole nazwy plikow, np. "](DEPLOY.md)") — dzialaly
tylko w starym katalogu; przeliczone recznie
Objete m.in.: CLAUDE.md (scripts/onboard/README.md -> kb/runbooks/
node-onboarding-tool.md, docs/backlog.md -> kb/phases/backlog.md),
README.md, .claude/skills/, 20 session logow, kod jobow.
Ostatnie 5 odwolan pochodzi z tresci wciagnietej rebasem z origin/master
(session log 2026-07-31, override node-agenta na SOLARII, dwie pozycje
backlogu) — wskazywaly na docs/incidents/, docs/kb/modules/ i
services/narty27/README.md sprzed migracji.
Dodany wzajemny link miedzy kb/services/control-plane.md (stub kodu)
a kb/subsystems/control-plane.md (opis, deprecated) — dwa dokumenty o tym
samym systemie, latwe do pomylenia.
Weryfikacja na 790 plikach: 0 odwolan do starych sciezek,
0 martwych linkow markdown. Lint OKF: 190/190 plikow ZGODNE.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# Homelab Codex
|
|
|
|
GitOps-lite orchestration for a distributed homelab environment.
|
|
|
|
## Architecture
|
|
|
|
The homelab consists of several nodes connected via a Tailscale internal mesh.
|
|
|
|
| Host | Role | Description |
|
|
|------|------|-------------|
|
|
| **SATURN** | Primary Node | Development, orchestration, and git source of truth (commit node). |
|
|
| **SOLARIA** | Compute Node | GPU, inference, and heavy compute workloads. |
|
|
| **PIHA** | Infra Node | Core infrastructure services, automation, and monitoring. |
|
|
| **VPS** | Edge Node | Public ingress, reverse proxy, and edge services. |
|
|
|
|
## Agent System
|
|
|
|
The homelab uses a multi-agent orchestration model with human-in-the-loop for destructive actions:
|
|
|
|
| Agent | Node | Role |
|
|
|-------|------|------|
|
|
| **stability-agent** | all nodes | Per-node watchdog — monitors Docker, disk, Tailscale, MQTT; emits events |
|
|
| **node-agent** | all nodes | Publishes container health events to Redis pub/sub |
|
|
| **observer** | VPS | Synthesizes world state from events into `/opt/homelab/world/*.json` |
|
|
| **supervisor** | VPS | Detects drift between desired and actual state; writes `pending` actions |
|
|
| **planner-agent** | SOLARIA | LLM-powered diagnosis — listens to Redis, proposes remediation actions |
|
|
| **executor** | VPS | Executes actions only after operator approval |
|
|
| **operator-ui** + **telegram-bot** | VPS / PIHA | Operator reviews and approves/rejects pending actions |
|
|
|
|
Action approval flow: `pending/` → operator approves → `approved/` → executor runs.
|
|
|
|
## Repository Structure
|
|
|
|
- `docs/`: [Infrastructure Standards](kb/subsystems/standards.md) and [Deployment Conventions](kb/subsystems/deployment.md).
|
|
- `kb/phases/subsystem-a-naprawa.md`: [Current Maintenance Plan (Control Plane)](kb/phases/subsystem-a-naprawa.md).
|
|
- `hosts/`: Host-specific configurations and service assignments.
|
|
- `services/`: Reusable Docker Compose service definitions.
|
|
- `scripts/`: Deployment and management scripts.
|
|
|
|
## Getting Started
|
|
|
|
1. **Standardization**: Follow the [Infrastructure Standards](kb/subsystems/standards.md).
|
|
2. **Deployment**: See [Deployment Conventions](kb/subsystems/deployment.md) for how to roll out changes.
|
|
3. **SATURN**: Remember that SATURN is the only node where commits should be made.
|
|
|
|
## Documentation Index
|
|
|
|
- [Current Maintenance Plan (Control Plane)](kb/phases/subsystem-a-naprawa.md)
|
|
- [Infrastructure Standards](kb/subsystems/standards.md)
|
|
- [Agent Operating Procedures](kb/subsystems/agent-operating-procedures.md) (For AI/Non-Human Agents)
|
|
- [Deployment Conventions](kb/subsystems/deployment.md)
|
|
- [Hardware](kb/nodes/legacy-hardware.md)
|
|
- [Networking](kb/subsystems/networking.md)
|
|
- [Services](kb/subsystems/legacy-services-list.md)
|
|
- [Node Capabilities](kb/subsystems/capability-model.md)
|
|
- [Action Model](kb/subsystems/action-approval-model.md)
|
|
|
|
---
|
|
*Note: This repository documents the state of the homelab. Runtime state lives outside the repository in `/opt/homelab`.*
|