Files

T

bart 41fb511877 Merge branch 'main' of https://git.bnhmeijer.nl/bart/cluster

2026-10-29 16:02:02 +01:00

13 KiB

Raw Blame History

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:

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).
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.
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.
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

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

# 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`)

# Alle debian packages in sources/ compileren
./package-repo/buildpackages.sh all

# Een specifiek package compileren
./package-repo/buildpackages.sh eendoe_hyperdeck

Kubernetes & Kustomize Inspectie

# 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

# 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`)

# 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 — Snelle cheatsheet en valkuilen voor ontwikkelaars en agents.
docs/platform.md — Volledige architectuur, domeinen, SSL-terminatie en GitOps-flow.
docs/cluster-status.md — Actuele clusterconfiguratie, node resources, PVC's en Ingress HTTPRoutes.
docs/repositories.md — Diepgaande details per repository en service.
docs/apache-reverse-proxy.md — Apache VirtualHost configuraties, SSL-certificaten en OIDC/Keycloak koppeling.

13 KiB Raw Blame History