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
• Git Submodules & Repositories
• Aan de Slag
  • Nieuwe clone inclusief submodules
  • Bestaande checkout bijwerken
  • Werken met submodules
• Platform Architectuur
• 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	https://git.bnhmeijer.nl/bart/cluster-infra.git	Kerninfrastructuur & middleware	PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto MQTT, Dnsmasq, Apache vhosts
k8s-infra-vmserver	https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git	GitOps configuratierepository	Kustomize manifests, Envoy Gateway HTTPRoutes, ArgoCD ApplicationSets
HERMS	https://git.bnhmeijer.nl/bart/HERMS.git	Geautomatiseerd brouwplatform	Rust microservices, Next.js frontend, ESP32 firmware, KiCad hardware
smart-home	https://git.bnhmeijer.nl/bart/smart-home.git	Huisautomatisering	Home Assistant, IoT netwerk- en migratiescripts
htpc	https://git.bnhmeijer.nl/bart/htpc.git	HTPC & Media Services	Jellyfin, *Arr stack, download clients, K8s manifests
eendoeserver	https://git.bnhmeijer.nl/bart/eendoeserver.git	Eendoe server configuratie	Website bronbestanden (eendoe/) en Apache vhosts (vhosts/)
package-repo	https://git.bnhmeijer.nl/bart/package-repo.git	Debian / APT package repository	Package bronnen (sources/), staging deb packages en CI workflow

---

🚀 Aan de Slag

Nieuwe clone inclusief submodules

Om deze repository inclusief alle onderliggende projecten direct te klonen:

git clone --recurse-submodules <repository-url>

Bestaande checkout bijwerken

Wanneer de repository al is gekloond zonder submodules, of om alle submodules te initialiseren:

git submodule update --init --recursive

Om alle submodules naar de nieuwste remote commits te synchroniseren:

git submodule update --remote --merge

Werken met submodules

1. Wijzigingen in code committen en pushen binnen de submodule zelf:

   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:

   cd ..
   git add cluster-infra
   git commit -m "chore(submodules): update cluster-infra reference"
   git push
   

---

🏛️ Platform Architectuur

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/:

• 📄 Platform Overzicht & Architectuur: Uitgebreide toelichting over de architectuur, lagen en principes.
• 🌐 Systeemarchitectuur & GitOps: Diepgaande uitleg over de GitOps pipeline, network ingress en storage.
• 📊 Live Cluster Status: Actuele hardware-specs, namespaces, pods, PVCs en routes op 10.2.0.4.
• 🛡️ Apache Reverse Proxy & VHosts: VHosts configuraties, SSL terminatie en OIDC authenticatie.
• 📦 Repository Details & Modules: Mappenstructuur, protocollen (MQTT/NATS) en microservices.
• 🚜 Grasmaaier Automatisering (OpenMower / Mowgli): Yardforce 500 robotmaaier met Mowgli, ROS Noetic, RTK GPS, Docker stack en MQTT-koppeling.
• 💡 Developer & Agent Cheatsheet: Handige commando's, git conventies en valkuilen.