HomeLabScripts/README.md

HomeLabScripts

HomeLabScripts ist ein Infrastruktur-Repository fuer mein HomeLab auf Basis von K3s. Es enthaelt Installationsskripte, Kubernetes-Manifeste und Helm-Values fuer mehrere Self-Hosting-Services.

Ziele

• Reproduzierbarer Aufbau eines K3s-Clusters
• Betrieb zentraler Self-Hosting-Dienste im Heimnetz
• Trennung von Storage-Workloads zwischen NFS (gross) und Longhorn (lokal/schnell)
• Nachvollziehbare Betriebsablaeufe ueber Skripte und YAML-Manifeste

Tech-Stack

• K3s (Kubernetes)
• Helm
• NFS
• Longhorn
• MariaDB / PostgreSQL / Redis
• Authentik

Repository-Struktur

HomeLabScripts/
├── k3s/
│   ├── install.sh
│   ├── get_helm.sh
│   ├── installHelm.sh
│   ├── k8sUser/
│   │   └── addUser.sh
│   └── apps/
│       ├── authentik/
│       ├── dashboard/
│       ├── gitea/
│       ├── gitLab/
│       ├── homarr/
│       ├── longhorn/
│       ├── Nextcloud/
│       ├── nfs-pv/
│       ├── photo/
│       └── speedtest-tracker/
├── nfs/
│   ├── server.sh
│   ├── client.sh
│   ├── nfsClient2.sh
│   ├── nfsClient2SlowData.sh
│   └── nfsSlowData.sh
├── mountscript/
│   └── mount-plus.sh
└── WISSENSBASIS.md

Enthaltene Services (Auswahl)

• Authentik
• Kubernetes Dashboard
• Gitea
• GitLab
• Nextcloud
• Immich
• PhotoPrism
• iCloudPD
• Homarr
• Speedtest Tracker
• Longhorn

Storage-Strategie

• Longhorn fuer Datenbanken und kleinere persistente Volumes
• NFS fuer grosse RWX-Workloads wie Medien, Repositories und Cloud-Daten

Empfehlung:

• Performance-kritische DB-Workloads nicht auf langsames NFS legen
• RWX-Daten (z. B. Medien) bevorzugt auf NFS

Schnellstart (neu aufsetzen)

1. System vorbereiten (Kernel, Netzwerk, Zeitsync, DNS)
2. K3s installieren:
   • bash k3s/install.sh
3. Helm installieren:
   • bash k3s/installHelm.sh
4. Optionalen K8s-User/Kubeconfig erstellen:
   • bash k3s/k8sUser/addUser.sh
5. Storage bereitstellen:
   • NFS via Skripte unter nfs/
   • Longhorn-StorageClass unter k3s/apps/longhorn/
6. Apps schrittweise deployen (pro App-Ordner)

Deployment-Hinweise

• Erst Namespace und Secrets anwenden, dann Deployments/Stateful Workloads
• Bei Helm-basierten Setups zuerst values.yaml pruefen
• Migrationen (z. B. auf Longhorn) nur mit Backup durchfuehren
• NodeSelector, fsGroup und Permissions pro App pruefen

Wichtige Skripte

• k3s/install.sh: K3s-Installation
• k3s/installHelm.sh: Helm-Installation
• k3s/k8sUser/addUser.sh: ServiceAccount + RBAC + Kubeconfig
• k3s/apps/dashboard/getToken.sh: Dashboard-Token abrufen
• k3s/apps/Nextcloud/helm/cleanRestart.sh: Nextcloud sauber neu starten
• nfs/server.sh: NFS-Server einrichten
• nfs/client.sh: NFS-Client einrichten
• mountscript/mount-plus.sh: Datentraeger partitionieren/mounten

Konventionen

• Manifeste: *-deployment.yaml, *-service.yaml, *-secret.yaml, namespace.yaml
• Secrets nie im Klartext committen
• Keine produktiven Zugangsdaten in Doku oder Repo-Historie speichern
• Aenderungen pro App in kleinen, nachvollziehbaren Commits

Sicherheit

• Bereits veroeffentlichte Tokens/Passwoerter sofort rotieren
• Secrets ueber Kubernetes Secrets oder externe Secret-Manager verwalten
• Admin-UIs nur intern oder hinter Authentik/Ingress absichern
• Regelmaessige Backups fuer DB und Volumes einplanen

Betrieb und Troubleshooting

Nuetzliche Kommandos:

kubectl get pods -A
kubectl get pvc -A
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

Falls ein Dienst nicht startet:

1. Namespace und Secret vorhanden?
2. PVC gebunden?
3. DB erreichbar?
4. Berechtigungen (uid/gid, fsGroup, NFS export options) korrekt?

Roadmap (optional)

• Einheitliche Ingress-Strategie fuer alle Services
• Zentralisiertes Secret-Management (z. B. SOPS/Sealed Secrets/Vault)
• Monitoring/Alerting (Prometheus + Grafana + Alertmanager)
• CI-Pruefungen fuer Manifeste (lint/validate)

Hinweis

Details zu bestehenden Setups und internen Notizen stehen in WISSENSBASIS.md. Diese README dient als zentraler Einstiegspunkt fuer Aufbau und Betrieb.