🏠 keller.io — Homelab GitOps

Der gesamte Cluster-Zustand als Code — ausgerollt rein über Git.

Deklaratives Kubernetes-Setup für einen Homelab-Cluster auf Talos Linux, kontinuierlich abgeglichen durch ArgoCD.

---

Der gesamte Cluster-Zustand ist in diesem Repository beschrieben — Änderungen passieren ausschließlich über Git-Commits, nicht per kubectl edit.

Hinweis — Blaupausen-Phase: Alle Manifeste sind funktionsbereite Vorlagen mit Platzhaltern (*.jit.platzhalter, CHANGE ME, REPLACE_ME). Was bis zum Produktivbetrieb noch fehlt, steht in docs/PRODUCTION-READINESS.md.

---

Inhaltsverzeichnis

• Wie es funktioniert
• Repository-Aufbau
• Plattform-Komponenten
• Anwendungen
• Entwicklungsumgebung (Nix Shell)
• Lokale Validierung
• Secrets verwalten (SOPS + age)
• Cluster-Bootstrap
• Weiterführende Dokumentation
• Lizenz

---

Wie es funktioniert

Das Repo folgt dem App-of-Apps-Pattern: Eine ArgoCD-Root-Application zeigt auf clusters/main/ und erzeugt von dort aus zwei ApplicationSets — eines für die Plattform-Infrastruktur, eines für die Anwendungen. Jede Komponente wird per Kustomize gerendert (Helm-Charts werden über helmCharts: inflationiert), sodass ArgoCD am Ende reine Kubernetes-Manifeste anwendet.

Git push ──▶ ArgoCD (root-app) ──▶ ApplicationSets ──▶ Kustomize/Helm ──▶ Cluster

---

Repository-Aufbau

Pfad	Inhalt
clusters/main/	ArgoCD-Einstiegspunkte: root-app.yaml, projects.yaml, ApplicationSets für Infrastruktur und Apps
infrastructure/base/	Plattform-Services (CNI, Ingress, Operatoren, Authentik, Monitoring) als Kustomize-Bases mit Helm-Inflation
infrastructure/overlays/main/	Cluster-spezifische Patches der Infrastruktur
apps/base/	Anwendungs-Blaupausen (je App: Workload, Datenbank, Cache, Backup, Secret-Vorlage)
apps/overlays/main/	Cluster-spezifische Patches (Hostnamen etc.) — von der ApplicationSet automatisch ausgerollt
docs/	Production-Readiness-Checkliste, Runbooks und Learnings
scripts/	CI-Helfer und Migrationswerkzeuge
justfile	Task-Runner für die gängigen Workflows (build, test, lint, secrets-check)
flake.nix / .envrc	Reproduzierbare Entwicklungsumgebung (siehe unten)
renovate.json	Automatische Dependency-Updates (Helm-Charts, Container-Images)
.sops.yaml	Verschlüsselungsregeln für Secrets
.forgejo/workflows/	CI-Pipeline (Render-, Schema- und Secret-Checks)

---

Plattform-Komponenten

Diese Dienste bilden das Fundament des Clusters und liegen unter infrastructure/base/.

Komponente	Aufgabe
ArgoCD	GitOps-Controller — gleicht den Cluster-Zustand kontinuierlich mit diesem Repo ab
Cilium	CNI / Netzwerk-Layer (eBPF-basiertes Pod-Networking & Policies)
NGINX Ingress	Ingress-Controller — externer HTTP(S)-Zugang zu den Anwendungen
cert-manager	Automatische TLS-Zertifikate (Let's Encrypt via DNS-01)
Authentik	Identity-Provider / OIDC — Single Sign-On, mit Blueprints pro App
CloudNativePG (CNPG)	PostgreSQL-Operator inkl. Backups (Barman → S3)
mariadb-operator	MySQL/MariaDB-Operator (z. B. für WordPress)
Valkey	Redis-kompatibler Cache — eine kleine, eigenständige Instanz pro App (apps/base/*/cache.yaml)
VictoriaMetrics + Grafana	Monitoring-Stack (Metriken, Dashboards, Alerting)
Ceph (Storage)	Persistenter Speicher: RBD (Block), CephFS (Datei), S3 (Objekt)
SOPS + age	Verschlüsselung von Secrets im Git-Repo (KSOPS im ArgoCD repo-server)
Renovate	Hält Helm-Chart- und Image-Versionen automatisch aktuell
Kubernetes MCP Server	Cluster-Observability für KI-Agenten (read-only, HTTP Basic Auth)

---

Anwendungen

Die ausgerollten Workloads liegen unter apps/base/ (Blaupause) und apps/overlays/main/ (Cluster-Variante).

Anwendung	Beschreibung
Forgejo	Git-Hosting (diese Plattform)
Kimai	Zeiterfassung
Mastodon	Föderiertes soziales Netzwerk
Paperless-ngx	Dokumenten-Management / Archiv
Roundcube	Webmail-Oberfläche (externer Mailserver)
Mailman	Mailinglisten-Verwaltung mit Postorius/HyperKitty
Icecast	Audio-Streaming-Server
phpMyAdmin	Web-Admin für MariaDB/MySQL-Instanzen
WordPress (×3)	Drei separate WordPress-Instanzen
Collabora	Online-Office (Dokumentenbearbeitung)
Renovate	Self-hosted Dependency-Update-Bot (CronJob)

---

Entwicklungsumgebung (Nix Shell)

Alle benötigten Werkzeuge sind in flake.nix gepinnt — keine manuelle Installation nötig.

nix develop          # Dev-Shell mit allen Tools betreten

Mit direnv lädt sich die Shell beim Betreten des Verzeichnisses automatisch (eine .envrc mit use flake liegt bereits im Repo):

direnv allow         # einmalig erlauben

Enthaltene Werkzeuge: just, kustomize, kubeconform, helm, sops, age, yamllint, kubectl.

---

Lokale Validierung

Vor jedem Commit lassen sich alle Manifeste lokal prüfen — identisch zur CI:

just build          # rendert jede Overlay mit kustomize (Helm-Inflation)
just test           # rendert + validiert gegen Kubernetes-/CRD-Schemas
just lint           # YAML-Linting
just secrets-check  # stellt sicher, dass kein *.sops.yaml unverschlüsselt ist

just ohne Argument listet alle verfügbaren Recipes auf.

---

Secrets verwalten (SOPS + age)

Secrets werden verschlüsselt im Repo abgelegt (*.sops.yaml). Nur data/stringData werden chiffriert — Metadaten bleiben lesbar und diffbar.

age-keygen -o age.agekey                 # 1. age-Schlüssel erzeugen (privat, NICHT committen)
# 2. Public Key in .sops.yaml unter creation_rules eintragen
just encrypt apps/base/forgejo/secret.sops.yaml   # 3. Secret verschlüsseln
just decrypt apps/base/forgejo/secret.sops.yaml   #    bzw. zum Ansehen entschlüsseln

Der private age-Key gehört niemals ins Git — er ist bereits in .gitignore ausgeschlossen. Im Cluster liegt er als sops-age-Secret für den ArgoCD repo-server.

---

Cluster-Bootstrap (Kurzform)

1. Talos-Cluster aufsetzen, kubeconfig beziehen.
2. ArgoCD installieren.
3. age-Key als sops-age-Secret im argocd-Namespace anlegen.
4. Root-Application anwenden:

   kubectl apply -f clusters/main/root-app.yaml
   

Ab hier übernimmt ArgoCD und rollt Infrastruktur und Apps aus. Detaillierte Schritte: docs/PRODUCTION-READINESS.md.

---

Weiterführende Dokumentation

• AGENTS.md — Architektur-Prinzipien & Arbeitsregeln
• docs/PRODUCTION-READINESS.md — Weg zur Produktion
• docs/runbooks/ — Betriebsabläufe
• docs/learnings/ — gesammelte Erkenntnisse
• docs/decisions/ — Architecture Decision Records

---

Lizenz

Veröffentlicht unter der BSD-3-Clause-Lizenz.