feat: initialise cluster superproject with submodules and platform docs

2026-10-18 14:22:34 +02:00
commit a362b05637
14 changed files with 734 additions and 0 deletions
@@ -0,0 +1,16 @@
+# OS generated files
+.DS_Store
+Thumbs.db
+
+# Editor directories and files
+*.swp
+*.swo
+*~
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+# Temporary / log files
+*.log
+scratch/
@@ -0,0 +1,12 @@
+[submodule "cluster-infra"]
+	path = cluster-infra
+	url = https://git.bnhmeijer.nl/bart/cluster-infra.git
+[submodule "HERMS"]
+	path = HERMS
+	url = https://git.bnhmeijer.nl/bart/HERMS.git
+[submodule "k8s-infra-vmserver"]
+	path = k8s-infra-vmserver
+	url = https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git
+[submodule "smart-home"]
+	path = smart-home
+	url = https://git.bnhmeijer.nl/bart/smart-home.git
@@ -0,0 +1,119 @@
+# Homelab Cluster Platform
+
+Centrale Git meta-repository voor de homelab Kubernetes infrastructuur, domotica en gespecialiseerde automatiseringsdiensten van `bnhmeijer.nl` op `vmserver` (`10.2.0.4`).
+
+---
+
+## 🧭 Inhoudsopgave
+
+- [Overzicht](#-overzicht)
+- [Git Submodules & Repositories](#-git-submodules--repositories)
+- [Aan de Slag](#-aan-de-slag)
+  - [Nieuwe clone inclusief submodules](#nieuwe-clone-inclusief-submodules)
+  - [Bestaande checkout bijwerken](#bestaande-checkout-bijwerken)
+  - [Werken met submodules](#werken-met-submodules)
+- [Platform Architectuur](#-platform-architectuur)
+- [Documentatie](#-documentatie)
+
+---
+
+## 📌 Overzicht
+
+Deze repository fungeert als **superproject** dat alle componenten van het platform samenbrengt:
+* **Infrastructurele Services**: Databases, caching, messaging en reverse proxy configuraties.
+* **GitOps & Deployment**: Volledig geautomatiseerde uitrol via Gitea Actions en ArgoCD.
+* **Brouwautomatisering (HERMS)**: IoT hardware, firmware, Rust controllers en een Next.js interface.
+* **Smart Home**: Home Assistant en sensorkoppelingen binnen het Kubernetes cluster.
+
+---
+
+## 📦 Git Submodules & Repositories
+
+| Map / Submodule | Git Remote | Doel | Belangrijkste Componenten |
+| :--- | :--- | :--- | :--- |
+| **[`cluster-infra`](file:///home/bart/git/cluster/cluster-infra)** | `https://git.bnhmeijer.nl/bart/cluster-infra.git` | Kerninfrastructuur & middleware | PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto MQTT, Dnsmasq, Apache vhosts |
+| **[`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | `https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git` | GitOps configuratierepository | Kustomize manifests, Envoy Gateway HTTPRoutes, ArgoCD ApplicationSets |
+| **[`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 |
+
+---
+
+## 🚀 Aan de Slag
+
+### Nieuwe clone inclusief submodules
+Om deze repository inclusief alle onderliggende projecten direct te klonen:
+```bash
+git clone --recurse-submodules <repository-url>
+```
+
+### Bestaande checkout bijwerken
+Wanneer de repository al is gekloond zonder submodules, of om alle submodules te initialiseren:
+```bash
+git submodule update --init --recursive
+```
+
+Om alle submodules naar de nieuwste remote commits te synchroniseren:
+```bash
+git submodule update --remote --merge
+```
+
+### Werken met submodules
+1. Wijzigingen in code committen en pushen binnen de submodule zelf:
+   ```bash
+   cd cluster-infra
+   git checkout main
+   git commit -am "feat: nieuwe configuratie"
+   git push origin main
+   ```
+2. De nieuwe submodule status vastleggen in deze root repository:
+   ```bash
+   cd ..
+   git add cluster-infra
+   git commit -m "chore(submodules): update cluster-infra reference"
+   git push
+   ```
+
+---
+
+## 🏛️ Platform Architectuur
+
+```mermaid
+flowchart TD
+    WAN([Internet / LAN]) --> Apache["Apache Reverse Proxy (vmserver: 10.2.0.4)"]
+    
+    subgraph Host ["vmserver Bare-Metal"]
+        Apache -->|SSL & OIDC| Keycloak["Keycloak (login.bnhmeijer.nl)"]
+        Apache --> Gitea["Gitea (git.bnhmeijer.nl)"]
+        Apache --> Media["Nextcloud / Jellyfin / *Arr"]
+        Apache -->|Envoy Gateway NodePort 32608| Gateway["Envoy Gateway API"]
+    end
+
+    subgraph K8s ["Kubernetes Cluster"]
+        Gateway --> Routes[HTTPRoutes]
+        Routes --> InfraWeb["Infra Web Dashboard"]
+        Routes --> HomeAssistant["Home Assistant"]
+        Routes --> HermsUI["HERMS UI"]
+        
+        ArgoCD["ArgoCD GitOps"] -->|Sync Manifests| K8sWorkloads[Deployments / Services / ConfigMaps]
+    end
+
+    subgraph CI_CD ["CI/CD Pipeline"]
+        Gitea -->|Push Trigger| Actions["Gitea Actions"]
+        Actions -->|Build & Push Image| Registry["Container Registry"]
+        Actions -->|Update Image Tags| GitOpsRepo["k8s-infra-vmserver"]
+        GitOpsRepo --> ArgoCD
+    end
+```
+
+---
+
+## 📚 Documentatie
+
+Alle gedetailleerde platformdocumentatie bevindt zich in de map **[`docs/`](file:///home/bart/git/cluster/docs)**:
+
+* 📄 **[Platform Overzicht & Architectuur](file:///home/bart/git/cluster/docs/platform.md)**: Uitgebreide toelichting over de architectuur, lagen en principes.
+* 🌐 **[Systeemarchitectuur & GitOps](file:///home/bart/git/cluster/docs/architecture.md)**: Diepgaande uitleg over de GitOps pipeline, network ingress en storage.
+* 📊 **[Live Cluster Status](file:///home/bart/git/cluster/docs/cluster-status.md)**: Actuele hardware-specs, namespaces, pods, PVCs en routes op `10.2.0.4`.
+* 🛡️ **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**: VHosts configuraties, SSL terminatie en OIDC authenticatie.
+* 📦 **[Repository Details & Modules](file:///home/bart/git/cluster/docs/repositories.md)**: Mappenstructuur, protocollen (MQTT/NATS) en microservices.
+* 💡 **[Developer & Agent Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Handige commando's, git conventies en valkuilen.
@@ -0,0 +1,29 @@
+# Cluster Workspace Documentatie
+
+Dit overzicht is bedoeld als referentie- en contextdocumentatie voor ontwikkelaars en AI-assistenten die werken binnen de werkmap `/home/bart/git/cluster`.
+
+---
+
+## 📌 Overzicht van de Workspace
+
+De werkmap `/home/bart/git/cluster` is een centrale **Git meta-repository** (superproject) voor het private home-server / homelab Kubernetes cluster. De individuele subsystemen zijn gekoppeld als **Git submodules** en synchroniseren autonoom met de private Gitea-instantie (`https://git.bnhmeijer.nl`).
+
+### Submodules in deze repository
+
+| Submodule | Doel | Primaire technologieën |
+| :--- | :--- | :--- |
+| **[`cluster-infra/`](file:///home/bart/git/cluster/cluster-infra)** | Infrastructurele services & middleware in K8s | K8s, Docker, Postgres, MongoDB, InfluxDB, RabbitMQ, Mosquitto, Dnsmasq, Apache/Nginx vhosts |
+| **[`HERMS/`](file:///home/bart/git/cluster/HERMS)** | Geautomatiseerd brouwplatform (Heat Exchange Recirculating Mash System) | Rust (Controller & Storage), Next.js / TypeScript (Frontend), ESP32 C++ (Firmware), KiCad (Hardware PCB), Python (Simulator) |
+| **[`k8s-infra-vmserver/`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | GitOps configuratie repository gemonitord door ArgoCD | Kubernetes Kustomize manifests, Gateway API (HTTPRoute) |
+| **[`smart-home/`](file:///home/bart/git/cluster/smart-home)** | Huisautomatisering en IoT integraties | Home Assistant / IoT configuraties |
+
+---
+
+## 📑 Documentatie-index
+
+* **[Platform Overzicht & Architectuur](file:///home/bart/git/cluster/docs/platform.md)**: Integraal platformoverzicht, subsystemen, beveiliging en GitOps principes.
+* **[Systeemarchitectuur & GitOps](file:///home/bart/git/cluster/docs/architecture.md)**: Hoe services, Gitea Actions pipelines, container registry, ArgoCD en Kubernetes samenwerken.
+* **[Live Cluster Status (10.2.0.4)](file:///home/bart/git/cluster/docs/cluster-status.md)**: Actuele status, node-specificaties, namespaces, pods, PVCs en HTTPRoutes van het actieve cluster.
+* **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**: Details over Apache op `10.2.0.4`, `/sites/vhosts`, TLS/OIDC terminatie en koppeling naar Envoy Gateway (NodePort 32608).
+* **[Repository Details & Modules](file:///home/bart/git/cluster/docs/repositories.md)**: Gedetailleerde beschrijving van alle componenten, mappen, protocollen (MQTT, NATS) en functies.
+* **[AI Cheatsheet & Developer Richtlijnen](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Snelle referentie voor commando's, submodule workflows, conventies en valkuilen.
@@ -0,0 +1,65 @@
+# AI Agent & Developer Cheatsheet
+
+Dit document bevat richtlijnen, veelvoorkomende commando's en belangrijke valkuilen voor het werken in deze workspace.
+
+---
+
+## ⚠️ Belangrijke Valkuilen & Regels
+
+1. **Root is de Git meta-repository (met Git submodules)**:
+   * `/home/bart/git/cluster` beheert het superproject, submodules en de overkoepelende documentatie in `docs/`.
+   * Gebruik `git submodule update --init --recursive` om submodules binnen te halen of bij te werken.
+   * Commits op codebase-niveau voer je uit binnen de desbetreffende submodule map (bijv. `git -C cluster-infra ...` of navigeer naar de map).
+   * Werk vervolgens desgewenst de submodule pointers bij in de root repository.
+2. **Submodule status & wijzigingen**:
+   * Let op 'dirty' of untracked files binnen submodules (`git status` in de root toont of een submodule gewijzigd is).
+3. **CI/CD Triggers via Path Filtering**:
+   * Zowel `cluster-infra` als `HERMS` gebruiken `dorny/paths-filter`. Wijzigingen in documentatie of mappen die niet in de filters staan triggeren geen container build.
+   * Controleer bij het toevoegen van nieuwe componenten of de workflow (`.gitea/workflows/*.yaml`) het pad herkent.
+4. **GitOps Manifest Synchronisatie**:
+   * Pas productie Kubernetes manifests bij voorkeur aan in de bronrepository (bijv. in `cluster-infra/<service>/k8s` of `HERMS/deployments`), zodat de CI/CD pipeline ze gesynchroniseerd kan overzetten naar `k8s-infra-vmserver`.
+   * Direct wijzigen in `k8s-infra-vmserver` kan leiden tot overschrijvingen bij een volgende geautomatiseerde build als dezelfde bestanden vanuit de bron worden gepusht.
+
+---
+
+## 🛠️ Snelle Commando's
+
+### Git Status over alle repositories
+```bash
+for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
+  echo "=== $d ==="
+  git -C "$d" status -s
+done
+```
+
+### Git Remotes verifiëren
+```bash
+for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
+  echo "=== $d ==="
+  git -C "$d" remote -v
+done
+```
+
+### Recente commits bekijken
+```bash
+for d in cluster-infra HERMS k8s-infra-vmserver smart-home; do
+  echo "=== $d ==="
+  git -C "$d" log -n 1 --oneline
+done
+```
+
+---
+
+## 🎨 Design & Coding Conventies
+
+* **Frontend (`HERMS/frontend`)**:
+  * **Thema**: SevenGrid Aurora Dark (`#0A0F12` background, Teal `#1DC7B7` accent, Coral `#E26F3A` verwarmingsaccent).
+  * **Styling**: Tailwind CSS met `rounded-full` pills voor status en switches.
+  * **Communicatie**: REST via storage API + WebSocket stream voor live telemetry.
+* **Backend Services (`HERMS`)**:
+  * Geschreven in **Rust** (Cargo workspace of individuele crates).
+  * Foutafhandeling met duidelijke loguitvoer (`tracing` / `log`).
+* **MQTT Topics**:
+  * Altijd strings voor heaters (`hlt`, `mlt`, `boil`).
+  * Telemetrie publiceren met `retain: true`.
+  * Commando's op `/cmd`, bevestiging op `/state`.
@@ -0,0 +1,86 @@
+# Apache Reverse Proxy & VHosts (`10.2.0.4`)
+
+Op host **`vmserver`** (`10.2.0.4`) draait Apache 2 direct als **Edge Reverse Proxy, TLS Terminator en OIDC Authentication Gateway** vóór zowel bare-metal hostdiensten als het Kubernetes cluster.
+
+---
+
+## 📂 Locatie & Synchronisatie
+
+* **Host-pad (live configuratie)**: `/sites/vhosts/`
+* **Git Repository**: [`cluster-infra/vhosts/`](file:///home/bart/git/cluster/cluster-infra/vhosts/) in `https://git.bnhmeijer.nl/bart/cluster-infra.git`
+* **Certificaten (Let's Encrypt)**: `/etc/letsencrypt/live/thuus.bnhmeijer.nl/`
+* **Certbot challenge root**: `/sites/certroot/.well-known`
+
+---
+
+## 🏗️ Architectuur: Apache als Edge Gateway
+
+```mermaid
+flowchart TD
+    Client[Inkomend Verkeer / Browser] -->|Poort 80 / 443| Apache["Apache 2 (10.2.0.4)<br>/sites/vhosts/"]
+
+    subgraph Apache Functionaliteit
+        Apache -->|TLS / Let's Encrypt| SSL[SSL Termination]
+        Apache -->|mod_auth_openidc| OIDC[OIDC Auth via login.bnhmeijer.nl]
+    end
+
+    subgraph Bare-Metal Host Services
+        Apache -->|Proxy :3000| Gitea[Gitea git.bnhmeijer.nl]
+        Apache -->|Proxy :8096| Jellyfin[Jellyfin /jellyfin]
+        Apache -->|Proxy :8000 / :5000| Radio[Icecast & Radio Chicken]
+        Apache -->|Proxy :8686, :7878, ...| ArrStack["*Arr Stack (Sonarr, Radarr, etc.)"]
+        Apache -->|DocRoot /sites/nextcloud| Nextcloud[cloud.bnhmeijer.nl]
+        Apache -->|Proxy 192.168.2.15:8123| HomeAssistant[ha.bnhmeijer.nl]
+    end
+
+    subgraph Kubernetes Cluster (vmserver:10.2.0.4)
+        Apache -->|Proxy 127.0.0.1:32608<br>(Envoy Gateway NodePort)| EnvoyGW[Envoy Gateway NodePort 32608]
+        EnvoyGW -->|HTTPRoute: herms.bnhmeijer.nl| HermsUI[herms frontend:3000]
+        EnvoyGW -->|HTTPRoute: login.bnhmeijer.nl| KeycloakK8s[keycloak:8080]
+        EnvoyGW -->|HTTPRoute: influx.bnhmeijer.nl| InfluxK8s[influxdb:8086]
+        EnvoyGW -->|HTTPRoute: thuus.bnhmeijer.nl/argocd| ArgoCDK8s[argocd-server:80]
+        EnvoyGW -->|HTTPRoute: infra.bnhmeijer.nl| InfraWebK8s[infra-web:3000]
+    end
+```
+
+---
+
+## 📑 Overzicht van VHosts (`/sites/vhosts/`)
+
+| Configuratiebestand | Domein / Hostname | Doel & Proxy Doel |
+| :--- | :--- | :--- |
+| [`001-main.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/001-main.conf) | `thuus.bnhmeijer.nl`, `10.2.0.4`, `vmserver.lan` (HTTP:80) | Port 80 redirect naar HTTPS + `/radio/` Icecast streaming |
+| [`001-main-le-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/001-main-le-ssl.conf) | `thuus.bnhmeijer.nl` (HTTPS:443) | **Hoofdportaal**: OIDC auth (Keycloak), Nextcloud alias, Jellyfin, Icecast, *Arr stack, `/argocd` via `127.0.0.1:32608` |
+| [`cloud.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/cloud.conf) & [`cloud-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/cloud-ssl.conf) | `cloud.bnhmeijer.nl` | Nextcloud DocumentRoot `/sites/nextcloud/` |
+| [`git.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/git.conf) | `git.bnhmeijer.nl` | Reverse proxy naar Gitea op `127.0.0.1:3000` (512MB body limit) |
+| [`hass.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/hass.conf) & [`hass-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/hass-ssl.conf) | `ha.bnhmeijer.nl` | Reverse proxy + WebSockets naar Home Assistant (`192.168.2.15:8123`) |
+| [`herms.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/herms.conf) & [`herms-int.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/herms-int.conf) | `herms.bnhmeijer.nl` | Reverse proxy + WebSockets naar Envoy Gateway NodePort (`127.0.0.1:32608`) |
+| [`keycloak.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/keycloak.conf) | `login.bnhmeijer.nl` | Reverse proxy naar Keycloak via Envoy Gateway NodePort (`127.0.0.1:32608`) |
+| [`influx-ui.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/influx-ui.conf) | `influx-ui.bnhmeijer.nl`, `influx-ui.lan` | Reverse proxy naar InfluxDB Explorer via Envoy Gateway NodePort (`127.0.0.1:32608`) |
+
+---
+
+## 🔐 OpenID Connect (OIDC) Configuratie
+
+In [`001-main-le-ssl.conf`](file:///home/bart/git/cluster/cluster-infra/vhosts/001-main-le-ssl.conf) verzorgt `mod_auth_openidc` Single Sign-On (SSO):
+* **Metadata URL**: `https://login.bnhmeijer.nl/realms/master/.well-known/openid-configuration`
+* **Client ID**: `apache-vmserver`
+* **Redirect URI**: `https://thuus.bnhmeijer.nl/oauth2/callback`
+* **Doorgegeven Headers**: Claims worden doorgestuurd als `X-User` (`%{OIDC-preferred_username}e`) en `X-Email` (`%{OIDC-email}e`). Interne OIDC headers worden gestript voordat verkeer naar backend-services gaat.
+
+---
+
+## ⚙️ Beheer & Herstarten op de Host
+
+Wanneer vhosts worden aangepast op de host `vmserver`:
+
+```bash
+# Configuratie testen
+sudo apache2ctl configtest
+
+# Apache herladen zonder downtime
+sudo systemctl reload apache2
+
+# Of volledige herstart
+sudo systemctl restart apache2
+```
@@ -0,0 +1,87 @@
+# Systeemarchitectuur & GitOps
+
+Dit document beschrijft de algehele architectuur van het homelab-cluster, het netwerkverkeer en de geautomatiseerde deployment-pipeline.
+
+---
+
+## 🏗️ GitOps & Deployment Pipeline
+
+Alle services volgen een strict GitOps-model aangedreven door **Gitea Actions** en **ArgoCD**:
+
+```mermaid
+flowchart TD
+    subgraph Development
+        Dev[Developer push naar main]
+    end
+
+    subgraph CI Pipeline ["Gitea Actions (git.bnhmeijer.nl)"]
+        Trigger[Push / PR Trigger] --> Filter[dorny/paths-filter: Detecteer gewijzigde componenten]
+        Filter -->|Component gewijzigd| Build[Bouw Docker Image]
+        Build --> PushReg[Push image naar Container Registry git.bnhmeijer.nl]
+        PushReg --> SyncGitOps[Update manifests met nieuwe tag in k8s-infra-vmserver]
+    end
+
+    subgraph GitOps Repo ["k8s-infra-vmserver (Git)"]
+        GitOpsPath["workloads/cluster-infra/<service>/"]
+    end
+
+    subgraph Kubernetes Cluster
+        Argo[ArgoCD ApplicationSet]
+        K8sWorkloads[K8s Deployments / Services / HTTPRoutes]
+    end
+
+    Dev --> Trigger
+    SyncGitOps -->|Commit & Push| GitOpsPath
+    GitOpsPath -->|Gemonitord via Git poll / webhook| Argo
+    Argo -->|Reconcile & Deploy| K8sWorkloads
+```
+
+### ArgoCD ApplicationSet
+In [`cluster-infra/argocd/applicationset.yaml`](file:///home/bart/git/cluster/cluster-infra/argocd/applicationset.yaml) is een ApplicationSet gedefinieerd:
+- **Repo URL**: `https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git`
+- **Directories**: `workloads/cluster-infra/*`
+- **Doel Namespace**: `cluster-infra`
+- **Sync Policy**: Geautomatiseerd (`prune: true`, `selfHeal: true`, `CreateNamespace=true`).
+
+Zodra een service manifests toevoegt onder `workloads/cluster-infra/<service>`, maakt ArgoCD automatisch een nieuwe applicatie aan (`cluster-infra-<service>`) en houdt deze synchroon.
+
+---
+
+## 🌐 Netwerk, Ingress & Routing (Apache + Envoy Gateway)
+
+Het externe netwerkverkeer wordt op twee lagen afgehandeld:
+
+1. **Edge Reverse Proxy & TLS/OIDC (Apache op `10.2.0.4`)**:
+   * Apache draait rechtstreeks op de host `vmserver` (`10.2.0.4`) en leest zijn configuraties uit **`/sites/vhosts/`** (versiebeheerd in [`cluster-infra/vhosts/`](file:///home/bart/git/cluster/cluster-infra/vhosts)).
+   * Verzorgt SSL-terminatie met Let's Encrypt certificaten (`/etc/letsencrypt/live/thuus.bnhmeijer.nl/`).
+   * Verzorgt OpenID Connect (OIDC) authenticatie via Keycloak (`https://login.bnhmeijer.nl`).
+   * Routeert lokaal naar bare-metal hostdiensten (Gitea op port 3000, Jellyfin, Icecast, *Arr stack, Nextcloud) en stuurt clusterverkeer door naar **Envoy Gateway NodePort `127.0.0.1:32608`**.
+   * Zie voor alle details: **[`docs/apache-reverse-proxy.md`](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**.
+
+2. **In-Cluster Gateway API (Envoy Gateway)**:
+   * Ontvangt verkeer vanaf Apache op NodePort `32608`.
+   * HTTPRoute resources koppelen domeinen en paden aan specifieke Kubernetes pods/services:
+     * `thuus.bnhmeijer.nl/argocd` $\rightarrow$ `argocd/argocd-server:80`
+     * `herms.bnhmeijer.nl` & `herms.lan` $\rightarrow$ `herms/frontend:3000`
+     * `login.bnhmeijer.nl` $\rightarrow$ `keycloak/keycloak:8080`
+     * `influx.bnhmeijer.nl` & `influx-ui.bnhmeijer.nl` $\rightarrow$ InfluxDB services in `cluster-infra`
+     * `infra.bnhmeijer.nl` $\rightarrow$ `cluster-infra/infra-web:3000`
+     * `gravitymon.lan` $\rightarrow$ `herms/gravitymon-2-nats:8002`
+
+---
+
+## 💾 Data & Berichtuitwisseling (Middleware Layer)
+
+Binnen het cluster worden verschillende persistente opslag- en messaging-engines gebruikt:
+
+1. **Mosquitto (MQTT)**:
+   * Broker voor IoT-hardware, sensoren en ESP32 firmware communicatie.
+   * Hoofdgebruiker: HERMS firmware/hardware en Home Assistant.
+2. **NATS**:
+   * Lichtgewicht high-throughput pub/sub event bus voor microservice-interne communicatie binnen HERMS.
+3. **InfluxDB**:
+   * Time-series database voor temperatuur- en procesmetingen van het brouwproces en sensordata.
+4. **PostgreSQL & MongoDB**:
+   * Relationele en document stores voor algemene cluster- en applicatiedata.
+5. **RabbitMQ**:
+   * Enterprise message broker voor asynchrone taken en wachtrijen.
@@ -0,0 +1,100 @@
+# Live Cluster Documentatie (`10.2.0.4`)
+
+Dit document beschrijft de actuele status, topologie, workloads en configuratie van het live Kubernetes cluster dat draait op host **`vmserver`** (`10.2.0.4`).
+
+---
+
+## 🖥️ 1. Node Specificaties & Host Details
+
+Het cluster draait momenteel als een gecombineerde single-node control-plane & worker:
+
+| Eigenschap | Waarde |
+| :--- | :--- |
+| **Node Naam** | `vmserver` |
+| **IP-Adres** | `10.2.0.4` *(gemigreerd vanaf `192.168.2.4` via [`migrate-k8s-node-ip.sh`](file:///home/bart/git/cluster/cluster-infra/migrate-k8s-node-ip.sh))* |
+| **Rollen** | `control-plane` (draait tevens workloads) |
+| **Kubernetes Versie** | `v1.37.0` |
+| **OS & Kernel** | Ubuntu 24.04.4 LTS / Linux `6.8.0-142-generic` (x86_64) |
+| **Container Runtime** | `containerd://2.2.1` |
+| **CPU Capaciteit** | 12 vCPU cores (~16% / 1.7 cores in gebruik) |
+| **Geheugencapaciteit** | 60.4 GiB RAM (~49% / 26.6 GiB in gebruik) |
+| **Lokale Opslag** | ~287 GB |
+
+---
+
+## 🌐 2. Cluster Networking & Ingress
+
+### Networking & CNI
+* **CNI Provider**: **Calico** (`calico-node` en `calico-kube-controllers`).
+* **Pod CIDR**: `10.10.174.0/...`
+* **Service CIDR**: `10.96.0.0/12`
+* **DNS**:
+  * **CoreDNS**: In-cluster DNS resolutie (`10.96.0.10`).
+  * **Dnsmasq**: Draait op het hostnetwerk (`10.2.0.4:53`) voor lokale domeinen (`*.lan`).
+
+### Gateway API & Ingress Routing
+De ingress-routering verloopt via **Envoy Gateway** met HTTPRoute configuraties:
+
+| Hostnames | Doelservice | Namespace | Doel |
+| :--- | :--- | :--- | :--- |
+| `thuus.bnhmeijer.nl` | `argocd-server:80` | `argocd` | ArgoCD Web UI & GitOps beheer |
+| `herms.bnhmeijer.nl`, `herms.lan` | `frontend:3000` | `herms` | HERMS Brouwinstallatie Web UI |
+| `login.bnhmeijer.nl` | `keycloak:8080` | `keycloak` | Keycloak Identity & Access Management |
+| `influx.bnhmeijer.nl`, `influx.lan` | `influxdb:8086` | `cluster-infra` | InfluxDB Time-Series API |
+| `influx-ui.bnhmeijer.nl`, `influx-ui.lan` | `influxdb-explorer:80` | `cluster-infra` | InfluxDB Web Explorer |
+| `infra.bnhmeijer.nl`, `infra.lan`, `dns.bnhmeijer.nl`, `dns.lan` | `infra-web:3000` | `cluster-infra` | Infra Web Dashboard & DNS beheer |
+| `gravitymon.lan` | `gravitymon-2-nats:8002` | `herms` | HTTP Ingress voor Gravitymon hydrometers |
+
+---
+
+## 💾 3. Opslag & Persistent Volumes (PVCs)
+
+Het cluster gebruikt Rancher's **`local-path-provisioner`** (`local-path-storage` namespace) als dynamische CSI provisioner:
+
+| Namespace | PVC Naam | Volume | Grootte | Toewijzing | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `cluster-infra` | `influxdb-storage-influxdb-0` | `pvc-6928459f-...` | 10 GiB | InfluxDB Data | **Bound** |
+| `cluster-infra` | `mongodb-data-mongodb-0` | `pvc-151480ce-...` | 10 GiB | MongoDB Data | **Bound** |
+| `cluster-infra` | `rabbitmq-data-rabbitmq-0` | `pvc-44ef79fe-...` | 5 GiB | RabbitMQ Queue Data | **Bound** |
+| `cluster-infra` | `influxdb-explorer-data` | `pvc-f03fb841-...` | 2 GiB | Explorer User State | **Bound** |
+| `cluster-infra` | `dnsmasq-data` | `pvc-1246f9a0-...` | 1 GiB | Dnsmasq Configuratie | **Bound** |
+| `keycloak` | `postgres-pvc` | `pvc-ad5f9b7d-...` | 1 GiB | Keycloak Database | **Bound** |
+
+---
+
+## 📦 4. Namespaces & Actieve Workloads
+
+### `herms` (Bierbrouwsysteem)
+* **`frontend`**: Next.js UI (SevenGrid Aurora Dark Mode).
+* **`herms-controller`**: Rust microservice voor stappen, PID-berekening en timers.
+* **`herms-storage`**: Rust opslag- en databeheerservice.
+* **`gravitymon-2-nats`**: Rust hydrometer event ingress.
+* **`nats`**: NATS message bus voor microservices.
+* **`mosquitto`**: MQTT broker voor communicatie met firmware / sensoren.
+
+### `cluster-infra` (Gedeelde Middleware)
+* **`influxdb-0`** & **`influxdb-explorer`**: Opslag en analyse van telemetriegegevens.
+* **`mongodb-0`**: NoSQL documentopslag.
+* **`rabbitmq-0`**: AMQP message broker.
+* **`dnsmasq`**: Lokale DNS server (HostPort 53).
+* **`email-service`**: Interne mailservice.
+* **`infra-web`**: Dashboard voor netwerk/infrastructuur.
+
+### `argocd` (GitOps Engine)
+* Bevat `argocd-server`, `argocd-repo-server`, `argocd-application-controller`, `argocd-applicationset-controller`, `argocd-dex-server`, `argocd-redis` en `argocd-notifications-controller`.
+* **Actieve ArgoCD Applicaties**:
+  * `cluster-infra-dnsmasq` (Healthy)
+  * `cluster-infra-email-service` (Healthy)
+  * `cluster-infra-influxdb` (Healthy)
+  * `cluster-infra-infra-web` (Healthy)
+  * `cluster-infra-mongodb` (Healthy)
+  * `cluster-infra-rabbitmq` (Healthy)
+  * `herms-suite` (Healthy)
+
+### `keycloak` (Identiteit & Toegangsbeheer)
+* **`keycloak`**: Quarkus-based Keycloak Server bereikbaar via `login.bnhmeijer.nl`.
+* **`postgres`**: Dedicated PostgreSQL database voor Keycloak realm-data.
+
+### `kube-system` & `envoy-gateway-system`
+* Control-plane componenten: `kube-apiserver`, `etcd`, `kube-controller-manager`, `kube-scheduler`, `kube-proxy`, `metrics-server`.
+* Data-plane en ingress proxies: `envoy-gateway` en `envoy-default-eg`.
@@ -0,0 +1,126 @@
+# Platform Overzicht & Architectuur
+
+Dit document biedt een integraal overzicht van het homelab- en serverplatform gehost op `vmserver` (`10.2.0.4`) binnen het domein `bnhmeijer.nl`.
+
+---
+
+## 🎯 Doel & Filosofie van het Platform
+
+Het platform fungeert als een betrouwbare, geautomatiseerde en zelf-gehoste infrastructurele backbone voor:
+1. **Centrale infrastructuurdiensten**: Databases, message brokers en interne netwerkdiensten.
+2. **GitOps & CI/CD**: Volledig geautomatiseerde build- en deploymentpijplijnen vanaf broncode tot Kubernetes pod.
+3. **Smart Home & IoT**: Integratie van domotica (Home Assistant) en sensoren in het thuisnetwerk.
+4. **Gespecialiseerde Automatisering (HERMS)**: Een geavanceerd biersysteem met sensoren, actuatoren, microservices en webinterfaces.
+
+---
+
+## 🏛️ Systeemlagen
+
+Het platform is opgebouwd in duidelijke scheiding van lagen:
+
+```mermaid
+flowchart TD
+    Internet([Publiek Internet / Lokaal LAN]) --> ApacheEdge["Apache Reverse Proxy (vmserver: 10.2.0.4)"]
+    
+    subgraph HostLevel ["Host Laag (vmserver / bare-metal)"]
+        ApacheEdge
+        Gitea["Gitea (git.bnhmeijer.nl)"]
+        Keycloak["Keycloak (login.bnhmeijer.nl)"]
+        MediaDiensten["Media & Storage (Jellyfin, Nextcloud, *Arr)"]
+        DnsmasqHost["Dnsmasq (Lokale DNS / DHCP)"]
+    end
+
+    ApacheEdge -->|SSL / OIDC Terminatie| Keycloak
+    ApacheEdge -->|Reverse Proxy| Gitea
+    ApacheEdge -->|Reverse Proxy| MediaDiensten
+    ApacheEdge -->|"Cluster Ingress (NodePort 32608)"| EnvoyGateway["Envoy Gateway API (k8s)"]
+
+    subgraph K8sCluster ["Kubernetes Cluster"]
+        EnvoyGateway --> HTTPRoutes[HTTPRoutes]
+        
+        subgraph Namespaces
+            subgraph NS_ClusterInfra ["namespace: cluster-infra"]
+                Postgres[(PostgreSQL)]
+                Mongo[(MongoDB)]
+                Influx[(InfluxDB)]
+                RabbitMQ[(RabbitMQ)]
+                Mosquitto[Mosquitto MQTT]
+                InfraWeb[Infra Web Dashboard]
+            end
+            
+            subgraph NS_SmartHome ["namespace: smart-home"]
+                HomeAssistant[Home Assistant]
+            end
+            
+            subgraph NS_HERMS ["namespace: herms"]
+                HermsFrontend[HERMS Web UI]
+                HermsController[HERMS Controller]
+                HermsStorage[HERMS Storage]
+                NATS[NATS Broker]
+            end
+
+            subgraph NS_ArgoCD ["namespace: argocd"]
+                ArgoCD[ArgoCD ApplicationSets]
+            end
+        end
+        
+        HTTPRoutes --> InfraWeb
+        HTTPRoutes --> HomeAssistant
+        HTTPRoutes --> HermsFrontend
+    end
+
+    subgraph GitOpsPipeline ["CI/CD & GitOps"]
+        Gitea -->|Gitea Actions CI| ContainerReg[Gitea Container Registry]
+        ContainerReg --> GitOpsCommit[Update manifests in k8s-infra-vmserver]
+        GitOpsCommit --> ArgoCD
+        ArgoCD -->|Reconcile & Deploy| Namespaces
+    end
+```
+
+---
+
+## 📦 Repositories & Submodules
+
+De werkmap `/home/bart/git/cluster` is gestructureerd als een **Git superproject** dat de verschillende subsystemen als submodules integreert:
+
+| Submodule | Doel | Primaire Stack |
+| :--- | :--- | :--- |
+| **[`cluster-infra`](file:///home/bart/git/cluster/cluster-infra)** | Kerninfrastructuur & databases in K8s | PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto, Dnsmasq, Apache vhosts |
+| **[`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | GitOps repository gemonitord door ArgoCD | Kubernetes Kustomize manifests, HTTPRoutes, Service definities |
+| **[`HERMS`](file:///home/bart/git/cluster/HERMS)** | Geautomatiseerd brouwplatform (brouwautomatisering) | Rust microservices, Next.js / TypeScript GUI, ESP32 C++, KiCad PCB |
+| **[`smart-home`](file:///home/bart/git/cluster/smart-home)** | Huisautomatisering & IoT | Home Assistant, netwerk- en migratiescripts |
+
+---
+
+## 🔒 Beveiliging, Ingress & Identiteitsbeheer
+
+1. **SSL / TLS**:
+   * Alle inkomende HTTPS-verbindingen worden afgehandeld door Apache met geautomatiseerde Let's Encrypt SSL-certificaten.
+2. **Authenticatie & Autorisatie (OIDC)**:
+   * Beschermde diensten worden beveiligd via `mod_auth_openidc` gekoppeld aan de centrale Keycloak-instantie (`https://login.bnhmeijer.nl`).
+3. **Cluster Routing**:
+   * Apache fungeert als edge gateway en forwardt verkeer bestemd voor Kubernetes pods naar **Envoy Gateway** via NodePort `127.0.0.1:32608`. Envoy routeert vervolgens op basis van `HTTPRoute` resources in de K8s namespaces.
+
+---
+
+## 🔄 GitOps Workflow
+
+De broncode en configuraties worden beheerd volgens strikte GitOps-principes:
+1. **Wijziging in Broncode**: Een ontwikkelaar pusht code naar `main` in bijv. `cluster-infra` of `HERMS`.
+2. **CI Pipeline (Gitea Actions)**:
+   * Detecteert gewijzigde componenten via `dorny/paths-filter`.
+   * Bouwt geoptimaliseerde Docker images en pusht deze naar de private Gitea container registry.
+   * Werkt de container image tag bij in de GitOps-repository [`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver).
+3. **CD Reconciliatie (ArgoCD)**:
+   * ArgoCD detecteert de gewijzigde manifests in `k8s-infra-vmserver`.
+   * Past automatisch een rolling update / sync toe op de Kubernetes cluster workloads.
+
+---
+
+## 📚 Verder Lezen
+
+* **[Systeemarchitectuur & GitOps Details](file:///home/bart/git/cluster/docs/architecture.md)**
+* **[Live Cluster Status & Hardware](file:///home/bart/git/cluster/docs/cluster-status.md)**
+* **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**
+* **[Repository- & Module-overzicht](file:///home/bart/git/cluster/docs/repositories.md)**
+* **[AI Agent & Developer Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**
@@ -0,0 +1,90 @@
+# Repository Details & Modules
+
+Dit document bevat specifieke details over de vier repositories in deze workspace, inclusief mappenstructuur, protocollen en configuraties.
+
+---
+
+## 1. 🍺 HERMS Repository
+
+* **Pad**: `/home/bart/git/cluster/HERMS`
+* **Git Remote**: `https://git.bnhmeijer.nl/bart/HERMS.git`
+* **Doel**: Geautomatiseerd Heat Exchange Recirculating Mash System (bierbrouwen).
+
+### Submodules & Componenten
+* **`frontend/`**:
+  * Next.js, React, Tailwind CSS.
+  * Geïmplementeerd met het SevenGrid Aurora Dark Mode thema (`#0A0F12`, Aurora Teal `#1DC7B7`, Coral `#E26F3A`).
+  * Realtime updates via WebSockets (`/api/ws`) en NATS opslag events (`herms.storage.>`).
+  * Live monitoring voor vaten: HLT (Warmtewisselaar), MLT (Maischketel), BK (Kookketel).
+* **`herms-controller/`**:
+  * Rust microservice.
+  * Beheert timers, receptstappen en automatische PID/doeltemperatuurberekeningen op basis van ketelafhankelijkheden (`depends_on`, `difference_abs`, `delay_minutes`).
+  * Publiceert doeltemperaturen naar MQTT.
+* **`herms-storage/`**:
+  * Rust REST API service met NATS integratie.
+  * Slaat recepten, batchlogs en telemetrie op.
+  * Schrijft metingen door naar InfluxDB (Line Protocol).
+* **`gravitymon-2-nats/`**:
+  * Rust microservice die HTTP POST data van Gravitymon hydrometers ontvangt en op NATS publiceert.
+* **`firmware/` & `mock-esp/`**:
+  * `firmware/`: C++ PlatformIO code voor de ESP32 microcontroller op de installatie.
+  * `mock-esp/`: Python simulator voor het nabootsen van keteltemperaturen, pompen en verwarmingselementen over MQTT.
+* **`bierpcb/`**:
+  * KiCad PCB project met schema's, relais-aansturingen, thermokoppelingangscircuits (MAX31855/MAX31856) en I2C IO expanders.
+* **`recepten/`**:
+  * JSON bierrecepten met stappen (maischstappen, kooktijden, ingrediënten).
+
+### MQTT Protocol Regels
+* **Base topic**: `<prefix>/<installation_id>/` (bijv. `avr59/hermsdev/` of `avr59/installation1/`).
+* **KeteI Identifiers (`<idx>`)**: Altijd string, nooit indexnummer (`hlt`, `mlt`, `boil`).
+* **Command-to-State regel**: Een commando op `.../<endpoint>/cmd` MOET direct door de ontvanger worden bevestigd op `.../<endpoint>/state` met `retain: true`.
+* **Telemetry**: Actuele temperatuur op `<base>heater/<idx>/temperature/state` (payload bijv. `"65.2"`).
+
+---
+
+## 2. 🌐 cluster-infra Repository
+
+* **Pad**: `/home/bart/git/cluster/cluster-infra`
+* **Git Remote**: `https://git.bnhmeijer.nl/bart/cluster-infra.git`
+* **Doel**: Gedeelde infrastructurele componenten en middleware.
+
+### Aanwezige Services
+* **`postgresql/`**: PostgreSQL cluster configuratie en persistent storage.
+* **`mongodb/`**: MongoDB replica/single instance.
+* **`influxdb/`**: InfluxDB time-series database.
+* **`rabbitmq/`**: AMQP message broker.
+* **`mosquitto/`**: Eclipse Mosquitto MQTT broker.
+* **`dnsmasq/`**: Lokale DNS caching en forwarding.
+* **`email-service/`**: Interne mailrelay / notificatiedienst.
+* **`infra-web/`**: Dashboard/webinterface voor infrastructuurbeheer.
+* **`vhosts/`**: Apache/Nginx SSL en non-SSL reverse proxy configuraties voor bnhmeijer.nl domeinen.
+* **`argocd/`**: ApplicationSet configuratie voor automatische ontdekking van workloads.
+
+### Hoe een nieuwe service toevoegen aan cluster-infra
+1. Maak een map aan: `mkdir -p <service-name>/k8s`
+2. Plaats eventueel een `Dockerfile` in `<service-name>/`.
+3. Voeg Kubernetes manifests toe in `<service-name>/k8s/` (`deployment.yaml`, `service.yaml`, `kustomization.yaml`).
+4. Commit & push naar `main`. De Gitea Actions workflow bouwt en synchroniseert dit automatisch naar `k8s-infra-vmserver`.
+
+---
+
+## 3. 🚀 k8s-infra-vmserver Repository
+
+* **Pad**: `/home/bart/git/cluster/k8s-infra-vmserver`
+* **Git Remote**: `https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git`
+* **Doel**: GitOps source-of-truth voor ArgoCD.
+
+### Mappenstructuur
+* **`workloads/`**:
+  * **`cluster-infra/`**: Wordt automatisch gevuld door CI/CD wanneer componenten in `cluster-infra` wijzigen.
+  * **`demo/`**: Bevat de demonstratieapplicatie (`podinfo`) en bijbehorende Gateway API `HTTPRoute` (`/demo`).
+  * **`herms/`**: De productiemanifests voor de HERMS microservices.
+
+---
+
+## 4. 🏠 smart-home Repository
+
+* **Pad**: `/home/bart/git/cluster/smart-home`
+* **Git Remote**: `https://git.bnhmeijer.nl/bart/smart-home.git`
+* **Doel**: Smart home configuraties (Home Assistant integraties, scripts, automatiseringen).
+* **Status**: In initiële opstartfase.