diff --git a/.gitmodules b/.gitmodules index 44ae6b6..95466fb 100644 --- a/.gitmodules +++ b/.gitmodules @@ -13,3 +13,9 @@ [submodule "htpc"] path = htpc url = https://git.bnhmeijer.nl/bart/htpc.git +[submodule "eendoeserver"] + path = eendoeserver + url = https://git.bnhmeijer.nl/bart/eendoeserver.git +[submodule "package-repo"] + path = package-repo + url = https://git.bnhmeijer.nl/bart/package-repo.git diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..27ae8ef --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,189 @@ +# 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. + +--- + +## โš ๏ธ 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 commit -m "..."`). + * Pas na het committen in de submodule werk je de submodule-pointer bij in deze root repository (`git add ` && `git commit`). + +2. **GitOps Manifest Synchronisatie (Bron vs. Bestemming)**: + * Pas Kubernetes manifests **altijd aan in de bronrepository** (bijv. `cluster-infra//k8s/` of `HERMS/deployments/` of `htpc/k8s/`). + * Wijzig manifests **niet direct handmatig** in `k8s-infra-vmserver/workloads/...` tenzij strikt noodzakelijk: Gitea Actions overschrijft deze mappen automatisch bij een nieuwe build vanuit de bronrepository! + +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`) +* **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: `//` (bijv. `avr59/installation1/` of `avr59/hermsdev/`). + * Ketel/Heater index: **altijd als string**, nooit numeriek (`hlt`, `mlt`, `boil`). + * Telemetrie publiceren met `retain: true` op `heater//temperature/state`. + * Commando-bevestiging: commando op `...//cmd` moet direct bevestigd worden op `...//state`. + +### ๐ŸŒ cluster-infra (`cluster-infra/`) +* Bevat configuraties voor gedeelde middleware. +* Toevoegen van een nieuwe service: + 1. Maak directory: `cluster-infra//k8s/`. + 2. Voeg eventuele `Dockerfile` toe in `cluster-infra//`. + 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`. + +--- + +## ๐Ÿ› ๏ธ 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; 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 +``` + +### 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 +``` + +--- + +## ๐Ÿ“š 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. diff --git a/README.md b/README.md index f3f932d..c26833e 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,8 @@ Deze repository fungeert als **superproject** dat alle componenten van het platf | **[`HERMS`](file:///home/bart/git/cluster/HERMS)** | `https://git.bnhmeijer.nl/bart/HERMS.git` | Geautomatiseerd brouwplatform | Rust microservices, Next.js frontend, ESP32 firmware, KiCad hardware | | **[`smart-home`](file:///home/bart/git/cluster/smart-home)** | `https://git.bnhmeijer.nl/bart/smart-home.git` | Huisautomatisering | Home Assistant, IoT netwerk- en migratiescripts | | **[`htpc`](file:///home/bart/git/cluster/htpc)** | `https://git.bnhmeijer.nl/bart/htpc.git` | HTPC & Media Services | Jellyfin, *Arr stack, download clients, K8s manifests | +| **[`eendoeserver`](file:///home/bart/git/cluster/eendoeserver)** | `https://git.bnhmeijer.nl/bart/eendoeserver.git` | Eendoe server configuratie | Website bronbestanden (`eendoe/`) en Apache vhosts (`vhosts/`) | +| **[`package-repo`](file:///home/bart/git/cluster/package-repo)** | `https://git.bnhmeijer.nl/bart/package-repo.git` | Debian / APT package repository | Package bronnen (`sources/`), staging deb packages en CI workflow | --- diff --git a/agents.md b/agents.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/agents.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/eendoeserver b/eendoeserver new file mode 160000 index 0000000..eb3e451 --- /dev/null +++ b/eendoeserver @@ -0,0 +1 @@ +Subproject commit eb3e451a87c63b4f9ad944edfbf6293f91256bea diff --git a/package-repo b/package-repo new file mode 160000 index 0000000..9cc903b --- /dev/null +++ b/package-repo @@ -0,0 +1 @@ +Subproject commit 9cc903b2a4390a6d333278374d19f5bad8c4c878