# 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 |
| **[`htpc`](file:///home/bart/git/cluster/htpc)** | `https://git.bnhmeijer.nl/bart/htpc.git` | HTPC & Media Services | Jellyfin, *Arr stack, download clients, K8s manifests |

---

## 🚀 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.
* 🚜 **[Grasmaaier Automatisering (OpenMower / Mowgli)](file:///home/bart/git/cluster/docs/grasmaaier.md)**: Yardforce 500 robotmaaier met Mowgli, ROS Noetic, RTK GPS, Docker stack en MQTT-koppeling.
* 💡 **[Developer & Agent Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**: Handige commando's, git conventies en valkuilen.