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,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)**