235 lines
13 KiB
Markdown
235 lines
13 KiB
Markdown
# AGENTS.md — Homelab Cluster Platform
|
|
|
|
Instructies, architectuurcontext, werkwijzen en richtlijnen voor AI-agents (en ontwikkelaars) die werken binnen deze repository workspace.
|
|
|
|
---
|
|
|
|
## 🎯 1. Overzicht & Doel van de Repository
|
|
|
|
Deze repository (`/home/bart/git/cluster`) is de centrale **Git meta-repository (superproject)** voor het homelab Kubernetes cluster, domotica en automatiseringsplatform van `bnhmeijer.nl`, gehost op de bare-metal server **`vmserver` (`10.2.0.4`)**.
|
|
|
|
Het platform omvat:
|
|
* **Infrastructuurdiensten**: Databases, messaging brokers, caching, lokale DNS/NTP en reverse proxy configuraties.
|
|
* **GitOps & CI/CD**: Volledig geautomatiseerde pipelines met Gitea Actions en ArgoCD.
|
|
* **HERMS Brouwplatform**: Geautomatiseerd Heat Exchange Recirculating Mash System (Rust microservices, Next.js frontend, ESP32 firmware, KiCad hardware).
|
|
* **Smart Home**: Home Assistant en IoT-koppelingen binnen Kubernetes.
|
|
* **HTPC & Media**: Jellyfin, `*Arr`-stack en downloadvoorzieningen.
|
|
* **Web & Reverse Proxy (`eendoeserver`)**: Apache VirtualHosts, reverse proxy configuraties en de website van `eendoe.nl` op `web03`.
|
|
* **Software Distributie (`package-repo`)**: Debian / APT package repository bronnen, build-scripts en CI/CD packaging pipelines.
|
|
|
|
---
|
|
|
|
## ⚠️ 2. Gouden Regels voor AI-Agents
|
|
|
|
Lees en volg deze regels nauwkeurig bij het uitvoeren van wijzigingen:
|
|
|
|
1. **Meta-repository & Submodules (NIET direct in root code committen)**:
|
|
* Deze workspace bestaat uit Git submodules.
|
|
* Wijzigingen aan broncode, configuraties of componenten horen thuis in de betreffende submodule map (`cluster-infra/`, `HERMS/`, `k8s-infra-vmserver/`, `smart-home/`, `htpc/`, `eendoeserver/`, `package-repo/`).
|
|
* Voer commits altijd uit binnen de submodule zelf (bijv. via `git -C <submodule> commit -m "..."`).
|
|
* Pas na het committen in de submodule werk je de submodule-pointer bij in deze root repository (`git add <submodule>` && `git commit`).
|
|
|
|
2. **GitOps Manifest Synchronisatie (Bron vs. Bestemming)**:
|
|
* **`k8s-infra-vmserver` is een pure GitOps target-repository:**
|
|
* Breng **nooit** direct handmatige wijzigingen of commits aan in `k8s-infra-vmserver/workloads/cluster-infra/` (of andere componenten die via CI/CD beheerd worden).
|
|
* Dit voorkomt configuratie-drift en mergeconflicten met de geautomatiseerde deployment bots (`Gitea Actions Bot`).
|
|
* **Single Source of Truth is de bronrepository:**
|
|
* Pas Kubernetes manifests **altijd aan in de respectievelijke bronrepository** (bijv. `cluster-infra/<dienst>/k8s/`, `HERMS/deployments/`, `htpc/k8s/`).
|
|
* Na een `git push` naar de bronrepository draait de Gitea Actions workflow (`.gitea/workflows/build-and-deploy.yaml`).
|
|
* Deze workflow synct gewijzigde manifests automatisch naar `k8s-infra-vmserver/workloads/...` met het commitbericht `ci(...): sync manifests (...)`.
|
|
* ArgoCD detecteert de commit in `k8s-infra-vmserver` en synct de workloads naar het live Kubernetes cluster.
|
|
|
|
3. **CI/CD Path Filtering (`dorny/paths-filter`)**:
|
|
* Zowel `cluster-infra` als `HERMS` gebruiken path filters in hun workflows (`.gitea/workflows/*.yaml`).
|
|
* Wijzigingen in uitsluitend markdown/documentatie of mappen die buiten het filter vallen, triggeren geen build of image deployment.
|
|
* Controleer bij nieuwe componenten altijd of het pad in de workflow staat geregistreerd.
|
|
|
|
4. **Productie-integriteit & Veiligheid**:
|
|
* Dit cluster draait live workloads (inclusief DNS, domotica en actieve databases).
|
|
* Voer **geen** destructieve commando's uit (`kubectl delete namespace`, geforceerde teardowns, data-volume deletes) zonder expliciete bevestiging van de gebruiker.
|
|
* Breng wijzigingen aan via GitOps (declaratief) in plaats van ad-hoc `kubectl edit` of `kubectl apply` op productieworkloads.
|
|
|
|
---
|
|
|
|
## 📦 3. Submodules & Componenten
|
|
|
|
| Map / Submodule | Remote Git URL | Stack & Technologieën | Doel & Kerncomponenten |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **`cluster-infra`** | `https://git.bnhmeijer.nl/bart/cluster-infra.git` | Docker, K8s manifests, Bash | PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto MQTT, Dnsmasq, Chrony NTP, Apache vhosts, Infra Web Dashboard |
|
|
| **`k8s-infra-vmserver`** | `https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git` | Kustomize, ArgoCD, Gateway API | GitOps source-of-truth voor ArgoCD, Gateway API HTTPRoutes, Kustomize overlays & ApplicationSets |
|
|
| **`HERMS`** | `https://git.bnhmeijer.nl/bart/HERMS.git` | Rust, Next.js, C++ (ESP32), KiCad | Brouwautomatisering: `herms-controller` (Rust), `herms-storage` (Rust REST/NATS), `frontend` (Next.js/Tailwind), `firmware`, KiCad PCB |
|
|
| **`smart-home`** | `https://git.bnhmeijer.nl/bart/smart-home.git` | YAML, Python, Home Assistant | Domotica, Home Assistant configuraties, IoT migratie- en koppelscripts |
|
|
| **`htpc`** | `https://git.bnhmeijer.nl/bart/htpc.git` | Docker, K8s manifests | Jellyfin media server, `*Arr`-suite (Sonarr, Radarr, Lidarr, Prowlarr), download clients |
|
|
| **`eendoeserver`** | `https://git.bnhmeijer.nl/bart/eendoeserver.git` | Apache vhosts, HTML, SASS | Website `eendoe.nl` en Apache VirtualHost configuraties van web03 |
|
|
| **`package-repo`** | `https://git.bnhmeijer.nl/bart/package-repo.git` | Debian packaging, Gitea Actions | Bronnen, staging en build-pipelines voor debian packages |
|
|
|
|
---
|
|
|
|
## 🏛️ 4. Systeemarchitectuur & Netwerkverkeer
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
WAN([Internet / Lokaal LAN]) --> Apache["Apache Reverse Proxy (vmserver: 10.2.0.4)"]
|
|
|
|
subgraph Host ["vmserver Bare-Metal (10.2.0.4)"]
|
|
Apache -->|SSL / OIDC| Keycloak["Keycloak (login.bnhmeijer.nl)"]
|
|
Apache --> Gitea["Gitea (git.bnhmeijer.nl)"]
|
|
Apache --> Media["Nextcloud / Jellyfin / *Arr"]
|
|
Apache -->|NodePort 32608| Envoy["Envoy Gateway API (k8s)"]
|
|
Dnsmasq["Dnsmasq (10.2.0.4:53)"]
|
|
Chrony["Chrony NTP (10.2.0.4:123)"]
|
|
end
|
|
|
|
subgraph K8s ["Kubernetes Cluster (Single-Node vmserver)"]
|
|
Envoy --> HTTPRoutes[Envoy Gateway HTTPRoutes]
|
|
|
|
HTTPRoutes --> InfraWeb["Infra Web (`infra.lan`, `infra.bnhmeijer.nl`)"]
|
|
HTTPRoutes --> InfluxUI["InfluxDB Explorer (`influx-ui.lan`)"]
|
|
HTTPRoutes --> HermsUI["HERMS Frontend (`herms.lan`, `herms.bnhmeijer.nl`)"]
|
|
HTTPRoutes --> ArgoServer["ArgoCD UI (`thuus.bnhmeijer.nl`)"]
|
|
HTTPRoutes --> GravMon["Gravitymon Ingress (`gravitymon.lan:8002`)"]
|
|
|
|
ArgoCD["ArgoCD Operator"] -->|Sync Manifests| Namespaces["Namespaces: cluster-infra, herms, smart-home, htpc"]
|
|
end
|
|
|
|
subgraph GitOps ["GitOps & CI/CD Pipeline"]
|
|
Gitea -->|Gitea Actions| Build["Container Build & Test"]
|
|
Build --> Reg["Gitea Container Registry"]
|
|
Reg --> PushManifests["Sync manifests naar k8s-infra-vmserver"]
|
|
PushManifests --> ArgoCD
|
|
end
|
|
```
|
|
|
|
### Belangrijke Netwerk- en Clusterparameters
|
|
* **Host IP**: `10.2.0.4` (`vmserver`, K3s/Kubernetes node)
|
|
* **Kubelet Probes**: Health probes (`readinessProbe` / `livenessProbe`) verbinden vanaf node-IP `10.2.0.4`
|
|
* **Edge Reverse Proxy**: Apache draait native op `vmserver` (`10.2.0.4`) vóór Envoy Gateway / hostdiensten
|
|
* **CNI & Pod CIDR**: Calico (`10.10.174.0/...`)
|
|
* **Service CIDR**: `10.96.0.0/12`
|
|
* **Cluster DNS**: CoreDNS op `10.96.0.10`
|
|
* **Opslagklasse**: `local-path` (`local-path-provisioner` in namespace `local-path-storage`)
|
|
|
|
---
|
|
|
|
## 💻 5. Tech Stacks & Conventies per Component
|
|
|
|
### 🍺 HERMS (`HERMS/`)
|
|
* **Frontend (`frontend/`)**:
|
|
* Next.js, React, Tailwind CSS.
|
|
* **Thema**: *SevenGrid Aurora Dark*:
|
|
* Achtergrond: `#0A0F12`
|
|
* Accent primair: Aurora Teal `#1DC7B7`
|
|
* Accent verwarming/warning: Coral `#E26F3A`
|
|
* UI-elementen: `rounded-full` pills voor statusindicatoren en toggles.
|
|
* Communicatie: REST via `herms-storage` (`/api/...`) en realtime WebSockets (`/api/ws`) gevoed door NATS messaging.
|
|
* **Backend Microservices (`herms-controller/`, `herms-storage/`, `gravitymon-2-nats/`)**:
|
|
* Geschreven in **Rust** (Cargo).
|
|
* Logging via `tracing` / `log`.
|
|
* Integratie met InfluxDB (Line Protocol) en NATS message bus.
|
|
* **MQTT Communicatie Regels**:
|
|
* Base topic: `<prefix>/<installation_id>/` (bijv. `avr59/installation1/` of `avr59/hermsdev/`).
|
|
* Ketel/Heater index: **altijd als string**, nooit numeriek (`hlt`, `mlt`, `boil`).
|
|
* Telemetrie publiceren met `retain: true` op `<base>heater/<idx>/temperature/state`.
|
|
* Commando-bevestiging: commando op `.../<endpoint>/cmd` moet direct bevestigd worden op `.../<endpoint>/state`.
|
|
|
|
### 🌐 cluster-infra (`cluster-infra/`)
|
|
* Bevat configuraties voor gedeelde middleware.
|
|
* Toevoegen van een nieuwe service:
|
|
1. Maak directory: `cluster-infra/<service-name>/k8s/`.
|
|
2. Voeg eventuele `Dockerfile` toe in `cluster-infra/<service-name>/`.
|
|
3. Voeg manifests toe (`deployment.yaml`, `service.yaml`, `kustomization.yaml`).
|
|
4. Zorg dat de Gitea Actions workflow het pad oppakt in het path-filter.
|
|
|
|
### 🚀 k8s-infra-vmserver (`k8s-infra-vmserver/`)
|
|
* Bevat ArgoCD ApplicationSets en Kustomize base/overlay structuren voor het cluster.
|
|
* Map `workloads/` bevat gesynchroniseerde manifests voor `cluster-infra`, `herms`, `demo` en `htpc`.
|
|
|
|
### 🏢 eendoeserver (`eendoeserver/`)
|
|
* Bevat de configuratie en bestanden voor de standalone server `web03` (`eendoe.nl`):
|
|
* **`eendoe/`**: Document root voor de website `eendoe.nl` en `bm4.nl` (HTML, SASS, CSS, JS, afbeeldingen).
|
|
* **`vhosts/`**: Apache 2.4 VirtualHost configuraties (geïncludeerd via `Include /sites/vhosts/*.conf`).
|
|
* **Regels**:
|
|
* Grote binaire installers (zoals `.AppImage` of losse `.deb` installatiebestanden) horen **niet** thuis in git, maar worden beheerd via `package-repo` of downloads.
|
|
|
|
### 📦 package-repo (`package-repo/`)
|
|
* Bevat de bronbestanden en distributiestructuur voor de Debian/APT package repository van Eendoe:
|
|
* **`sources/`**: Bevat bronbestanden per package (bijv. `eendoe_repository`, `eendoe_hyperdeck`, `eendoe_srs`) met hun control templates en `bin/build.sh`.
|
|
* **`staging/`**: Bestemming voor nieuw gebouwde en bestaande `.deb` pakketten.
|
|
* **`binaries/`**: Publiek geserveerde repository bestanden (`pool/`, `dists/`).
|
|
* **`buildpackages.sh`**: Universeel build-script om packages direct te genereren.
|
|
* **`.gitea/workflows/build-and-publish.yaml`**: CI/CD pipeline voor automatische package-builds en SSH/rsync deployments.
|
|
* **Belangrijke regel**:
|
|
* **Nooit** grote externe database installatiebestanden (zoals Oracle Database XE deb packages van >2 GB) toevoegen aan deze repository.
|
|
|
|
---
|
|
|
|
## 🛠️ 6. Handige Commando's voor Agents
|
|
|
|
### Submodule & Git Beheer
|
|
```bash
|
|
# Submodule status en eventuele uncommitted changes inspecteren
|
|
for d in cluster-infra HERMS k8s-infra-vmserver smart-home htpc eendoeserver package-repo; do
|
|
echo "=== $d ==="
|
|
git -C "$d" status -s
|
|
done
|
|
|
|
# Alle submodules bijwerken naar de nieuwste remote commits
|
|
git submodule update --remote --merge
|
|
|
|
# Submodules initialiseren na clone
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
### Debian Packages Bouwen (`package-repo`)
|
|
```bash
|
|
# Alle debian packages in sources/ compileren
|
|
./package-repo/buildpackages.sh all
|
|
|
|
# Een specifiek package compileren
|
|
./package-repo/buildpackages.sh eendoe_hyperdeck
|
|
```
|
|
|
|
### Kubernetes & Kustomize Inspectie
|
|
```bash
|
|
# Pods bekijken over alle relevante namespaces
|
|
kubectl get pods -n cluster-infra
|
|
kubectl get pods -n herms
|
|
kubectl get pods -n argocd
|
|
kubectl get pods -n htpc
|
|
|
|
# Kustomize build lokaal valideren vóór commit
|
|
kubectl kustomize k8s-infra-vmserver/workloads/herms/
|
|
kubectl kustomize cluster-infra/postgresql/k8s/
|
|
```
|
|
|
|
### HERMS Backend (Rust) & Frontend
|
|
```bash
|
|
# Rust syntax- & typecheck
|
|
cargo check --manifest-path HERMS/herms-controller/Cargo.toml
|
|
cargo check --manifest-path HERMS/herms-storage/Cargo.toml
|
|
|
|
# Frontend build & linting
|
|
npm --prefix HERMS/frontend run lint
|
|
npm --prefix HERMS/frontend run build
|
|
```
|
|
|
|
### Eendoe Website & Server (`eendoeserver`)
|
|
```bash
|
|
# Website deployen naar productie (web03 / eendoe.nl)
|
|
rsync -avz eendoeserver/eendoe/ bart@eendoe.nl:/sites/eendoe/
|
|
|
|
# Live status controleren
|
|
curl -sI https://eendoe.nl | head -n 5
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 7. Documentatie Index
|
|
|
|
In de map `docs/` is gedetailleerde achtergrondinformatie beschikbaar:
|
|
* [`docs/agent-cheatsheet.md`](file:///home/bart/git/cluster/docs/agent-cheatsheet.md) — Snelle cheatsheet en valkuilen voor ontwikkelaars en agents.
|
|
* [`docs/platform.md`](file:///home/bart/git/cluster/docs/platform.md) — Volledige architectuur, domeinen, SSL-terminatie en GitOps-flow.
|
|
* [`docs/cluster-status.md`](file:///home/bart/git/cluster/docs/cluster-status.md) — Actuele clusterconfiguratie, node resources, PVC's en Ingress HTTPRoutes.
|
|
* [`docs/repositories.md`](file:///home/bart/git/cluster/docs/repositories.md) — Diepgaande details per repository en service.
|
|
* [`docs/apache-reverse-proxy.md`](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md) — Apache VirtualHost configuraties, SSL-certificaten en OIDC/Keycloak koppeling.
|