ADD: create initial README.md with project overview, goals, tech stack, and deployment instructions

Co-authored-by: Copilot <copilot@github.com>
2026-04-26 12:41:05 +02:00
1 changed files with 151 additions and 0 deletions
@@ -0,0 +1,151 @@
+# 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
+
+```text
+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:
+
+```bash
+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.