GitHub - pkr-lab/capulus-core: Fully automated, GitOps-driven single-node home server on k3s, ArgoCD & Tailscale — one Ansible run, zero open ports.

Vollständig automatisierter, GitOps-getriebener Home-Server auf einer einzigen Maschine.
Ein einziger Ansible-Run liefert einen gehärteten Ubuntu-Host, einen schlanken Kubernetes-Cluster (k3s), Continuous Delivery aus Git (ArgoCD) und Zero-Config-Remote-Access (Tailscale).

⚡ TL;DR

# 1) Repo klonen
git clone https://github.com/pkr-lab/capulus-core.git && cd capulus-core

# 2) Eigene Details eintragen (Server-IP, Repo-URL, Tailscale-Key)
$EDITOR ansible/inventory/hosts.yml
$EDITOR ansible/group_vars/all.yml

# 3) Collections installieren und Playbook laufen lassen
make install
# oder:
# ansible-galaxy collection install -r ansible/requirements.yml
# ansible-playbook -i ansible/inventory/hosts.yml ansible/site.yml --ask-vault-pass

Am Ende druckt das Playbook die ArgoCD-URL und das Admin-Passwort. Fertig.

Was du bekommst

Schicht	Komponente	Hinweis
Betriebssystem	Ubuntu Server 26.04 LTS	Gehärtet, UFW-Firewall, NTP-synced, Swap off
Kubernetes	k3s (latest stable)	Single-Node, Traefik, CoreDNS, local-path, metrics-server
GitOps	ArgoCD + ApplicationSets	Verzeichnis unter `argocd/apps/platform/` oder `argocd/apps/workloads/` anlegen → pushen → deployed
Split-DNS	dnsmasq auf `tailscale0`	`*.homeserver` aus LAN und Tailnet auflösbar
Werbeblocking	Pi-hole	Filtert DNS-Anfragen für alle Geräte, die dnsmasq bereits als DNS nutzen — kein Router-Eingriff nötig
Web-Ansible	Semaphore UI	Ein-Klick-`git pull && ansible-playbook` gegen das eigene LAN
Monitoring	VictoriaMetrics + Grafana	Single-Node TSDB, vmagent, vmalert, Alertmanager, Dashboards
Kubernetes-UI	Headlamp	Browser-Dashboard für den Cluster
Secrets	Sealed Secrets + kubeseal-webgui	Verschlüsselte Secrets in Git, nur im Cluster entschlüsselbar
Notifications	Gotify + ntfy	Self-hosted Push — Gotify (Android), ntfy (iOS + Android)
Live-Streaming	MediaMTX	RTMP/RTSP-Ingest → HLS-Playback; Publish/Zuschauer per interner mediamtx-Auth (Nutzername/Passwort)
Remote-Access	Tailscale	WireGuard-Mesh-VPN — keine Portfreigaben, keine öffentliche IP
Externe Erreichbarkeit	Cloudflare Tunnel	Ausgewählte Dienste öffentlich erreichbar, ohne VPN und ohne offene Ports
CI/CD intern	Argo Workflows + MinIO	Private CI/CD-Pipeline + S3-Artifact-Store im Cluster
Ingress	Traefik v2 (k3s bundled)	HTTP/HTTPS-Routing in den Cluster
Provisioning	Ansible (≥ 2.14)	Vollständig idempotent, Role-per-Concern, Vault für Secrets

Ziel-Hardware: kleine Box mit ≥ 4 GB RAM und ≥ 20 GB Disk. Referenz-Build: Intel i5, 32 GB RAM, 512 GB NVMe.

Auto-Upgrade-Details

auto_upgrade: true (Default) hält bei jedem Playbook-Run den gesamten Stack aktuell:

Komponente	Mechanismus
APT-Pakete	`apt dist-upgrade` + `unattended-upgrades` für tägliche Sicherheits-Patches
Tailscale	`state: latest` für das `tailscale`-Paket
k3s	Folgt `k3s_channel` (Default `stable`), pin via `k3s_version`
Helm	Re-Run des offiziellen Installers bei neuem Release
ArgoCD	`helm upgrade --install` ohne `--version`, pin via `argocd_version`
Reboot	Auto-Reboot wenn APT `/var/run/reboot-required` setzt (togglebar via `auto_reboot_if_required`)

Für reproduzierbare Builds: auto_upgrade: false in ansible/group_vars/all.yml.

Quickstart (5 Schritte)

Erstmalig auf der Maschine? Start mit Ubuntu-Server-Installation. Komplette Voraussetzungen: docs/a-betriebssystem/a0020-prerequisites.md.

Schritt-für-Schritt aufklappen

1. Repo klonen

git clone https://github.com/pkr-lab/capulus-core.git
cd capulus-core

2. Inventory auf den eigenen Server zeigen

$EDITOR ansible/inventory/hosts.yml
# ansible_host (Server-IP) und ggf. ansible_ssh_private_key_file anpassen.

3. Variablen setzen

$EDITOR ansible/group_vars/all.yml
# Pflicht: argocd_repo_url, local_subnet, timezone.
# Tailscale-Key muss vault-encrypted sein (nächster Schritt).

4. Tailscale-Auth-Key verschlüsseln

ansible-vault encrypt_string 'tskey-auth-DEIN_KEY' --name 'tailscale_auth_key'
# Den !vault-Block in all.yml über den bestehenden tailscale_auth_key-Wert pasten.

5. Playbook ausführen

make install
# oder ohne make:
ansible-galaxy collection install -r ansible/requirements.yml
ansible-playbook -i ansible/inventory/hosts.yml ansible/site.yml --ask-vault-pass

Ergebnis:

ArgoCD UI:  https://<server-ip>:30443
Username:   admin
Password:   <auto-generiert>

Repository-Layout

Verzeichnisstruktur anzeigen

capulus-core/
├── README.md
├── Makefile                          # Convenience-Targets: install, lint, ping, check, …
├── docs/
│   ├── TEMPLATE.md                   # Vorlage für neue Docs: Namensschema, Kategorien, Doc-Typen
│   ├── a-betriebssystem/             # Betriebssystem & Grundlagen
│   │   ├── a0000-ubuntu-server-install.md   # Bare-Metal-Ubuntu-Installation
│   │   ├── a0010-overview.md                # Architektur-Diagramme
│   │   ├── a0020-prerequisites.md           # Voraussetzungen & Pre-flight
│   │   ├── a0030-installation.md            # Step-by-Step-Setup
│   │   └── a0040-troubleshooting.md         # Häufige Probleme
│   ├── b-kubernetes-gitops/          # Kubernetes & GitOps
│   │   ├── b0000-k3s.md                     # k3s + kubectl-Referenz
│   │   ├── b0010-argocd.md                  # GitOps-Nutzung
│   │   ├── b0020-argocd-projects.md         # Platform/Workloads-AppProject-Trennung
│   │   ├── b0030-semaphore.md               # Semaphore-Web-UI für Ansible
│   │   └── b0040-hpa-autoscaling.md         # Horizontale Autoskalierung (HPA)
│   ├── c-netzwerk-dns/               # Netzwerk & DNS
│   │   ├── c0000-dns-architecture.md        # Split-DNS-Design & Ausfallsicherheit
│   │   ├── c0010-tailscale.md               # VPN-Setup
│   │   ├── c0020-pihole.md                  # Netzwerkweites Werbeblocking via Pi-hole
│   │   ├── c0030-port-uebersicht.md         # Port-/Ingress-Übersicht aller Apps
│   │   └── c0040-domain-tiers.md            # dev/tech/prod-URL-Konvention
│   ├── e-externe-erreichbarkeit/     # Externe Erreichbarkeit
│   │   ├── e0000-cloudflare-tunnel.md       # Cloudflare Tunnel — Setup & Konzept
│   │   └── e0010-cloudflare-deploy.md       # Cloudflare Tunnel — Deploy & Betrieb
│   ├── d-sicherheit/                 # Sicherheit
│   │   ├── d0000-incident-2026-08-12.md            # Incident-Report: ApplicationSet-Migration löscht 32 Apps
│   │   ├── d0010-security-hardening-roadmap.md     # Phasenplan der Security-Härtung
│   │   ├── d0020-crowdsec.md                       # Brute-Force-Schutz für SSH und Traefik
│   │   ├── d0030-network-policies.md               # Cluster-NetworkPolicies (Phase 3)
│   │   ├── d0040-internal-tls.md                   # Internes TLS für *.homeserver (Phase 5)
│   │   ├── d0050-secrets-encryption-audit-log.md   # Secrets-Encryption-at-Rest + Audit-Log (Phase 4)
│   │   └── d0060-secrets-rotation.md               # Secrets-Rotation-Checkliste (Phase 7)
│   ├── f-cicd-automatisierung/       # CI/CD & Automatisierung
│   │   ├── f0000-argo-workflows.md          # Private CI/CD mit Argo Workflows + MinIO
│   │   ├── f0020-renovate.md                # Automatische Update-PRs für Helm-Charts/Images
│   │   ├── f0030-release-automation.md      # GitHub Release bei jedem Merge auf main
│   │   ├── f0040-github-release-watcher.md  # GitHub-Release → Zammad-E-Mail-Benachrichtigung
│   │   └── f0050-gitlab-mirror.md           # Vollspiegelung zu GitLab als Redundanz für GitHub-Ausfall
│   ├── 1-benachrichtigungen/         # Benachrichtigungen
│   │   ├── 10000-gotify.md                  # Push-Notifications via Gotify
│   │   └── 10010-ntfy.md                    # iOS Push-Notifications via ntfy
│   ├── 2-betrieb-hardware/           # Betrieb & Hardware
│   │   ├── 20000-nas-storage.md             # NAS-StorageClass (NFS, UGREEN NAS)
│   │   ├── 20010-nas-backup.md              # Externe USB-Platte am NAS: regelmäßige Backups
│   │   ├── 20020-cluster-power-manager.md   # Worker per Wake-on-LAN je nach Homeserver-Last dazuschalten
│   │   ├── 20030-nightly-worker-update.md   # Nachts 01:00 Uhr: Worker per WoL wecken, apt-Update, wieder abschalten
│   │   └── 20040-printer.md                 # Samsung Xpress M2026 per CUPS im Heimnetz freigeben
│   ├── 3-apps-workloads/             # Apps & Workloads
│   │   ├── 30000-zammad.md                  # Zammad Helpdesk/Ticket-System
│   │   ├── 30010-alamos-apager.md           # Alarmmonitor-Kiosk-Verwaltung (ALAMOS AMweb)
│   │   ├── 30020-vereinsheim-alarmmonitor.md # Banana-Pi-Alarmmonitor-Kiosk fürs Vereinsheim
│   │   ├── 30030-wikijs.md                  # Wiki.js Team-Wiki
│   │   ├── 30040-mediamtx.md                # Live-Streaming (RTMP/RTSP → HLS)
│   │   ├── 30050-paperless-ngx.md           # Dokumentenmanagement mit OCR
│   │   ├── 30060-mealie.md                  # Rezeptverwaltung + Wochenplaner
│   │   ├── 30070-n8n.md                     # Low-Code-Automatisierung
│   │   ├── 30080-uptime-kuma.md             # Status-Seite und Service-Alerting
│   │   ├── 30090-rhein-dashboard.md         # Grafana: Pegelonline, DWD, ELWIS, Hochwasser RLP
│   │   ├── 300a0-vaultwarden.md             # Bitwarden-kompatibler Passwort-Manager
│   │   ├── 300b0-nextcloud.md               # Datei-Sync, Kalender, Kontakte
│   │   ├── 300c0-immich.md                  # Foto-/Video-Backup vom Handy
│   │   ├── 300d0-carplay-api.md             # Homeserver-Dashboard-API (iOS-App, inkl. power-agent)
│   │   ├── 300e0-xibosignage.md             # Xibo CMS + Bilder-Slideshow auf Raspberry Pi 3B+
│   │   └── 300f0-pacman-visitor-tracking.md # IP/GeoIP-Besucher-Tracking-Demo für die Schulung
│   ├── assets/banner.svg
│   └── superpowers/                  # Datierte Plan-/Spec-Docs, eigenes Namensschema
│       ├── plans/
│       └── specs/
├── renovate.json                     # Renovate-Konfiguration (siehe docs/f-cicd-automatisierung/f0020-renovate.md)
├── .releaserc.json                   # semantic-release-Konfiguration (siehe docs/f-cicd-automatisierung/f0030-release-automation.md)
├── .github/
│   └── workflows/
│       ├── release.yml               # semantic-release bei jedem Push auf main
│       └── mirror-gitlab.yml         # Vollspiegelung zu GitLab (siehe docs/f-cicd-automatisierung/f0050-gitlab-mirror.md)
├── ansible/
│   ├── site.yml                      # Entry-Point
│   ├── requirements.yml              # Galaxy-Collections
│   ├── ansible.cfg                   # Defaults
│   ├── inventory/hosts.yml           # Eigener Server (+ semaphore_targets)
│   ├── group_vars/all.yml            # Alle Knobs (vault-verschlüsselte Secrets)
│   └── roles/
│       ├── common/                   # Base-OS, Firewall, Pakete
│       ├── crowdsec/                 # Brute-Force-Schutz (SSH + Traefik-Logs)
│       ├── dnsmasq/                  # Split-DNS für *.homeserver, forwardet Rest an Pi-hole
│       ├── tailscale/                # VPN (WireGuard-Mesh)
│       ├── k3s/                      # Kubernetes Control-Plane + Helm
│       ├── k3s_agent/                # Kubernetes Worker-Node
│       ├── argocd/                   # GitOps-Controller via Helm
│       ├── semaphore_secrets/        # Bootstrap-Secret für den Semaphore-Pod
│       ├── semaphore_targets/        # SSH-Pubkey auf Managed-Hosts pushen
│       ├── semaphore_bootstrap/      # Projects/Inventories/Templates per API
│       ├── wake_on_lan/              # WoL-Empfangsbereitschaft auf worker-0/worker-1
│       ├── cluster_power_manager/    # Homeserver: weckt/schaltet Worker per WoL je nach Last
│       ├── cluster_power_manager_target/  # Worker: autorisiert Shutdown-Key (nur poweroff)
│       ├── power_agent/              # Homeserver: HTTP-API für manuelle Helligkeit/Wake/Shutdown aus der iOS-App
│       ├── nightly_worker_wake/      # Homeserver: 01:00-Uhr-Timer weckt Worker, triggert Semaphore-Update, fährt wieder herunter
│       ├── worker_apt_update/        # Worker: apt update/dist-upgrade (fehlt sonst, da keine common-Rolle)
│       ├── cups_print_server/        # Homeserver: USB-Drucker per IPP/AirPrint freigeben
│       ├── thermal_watchdog/         # Selbst-Abschaltung bei Übertemperatur (alle Knoten + Kiosks)
│       ├── resource_watchdog/        # Selbst-Abschaltung bei Dauerlast (alle Knoten + Kiosks)
│       ├── alamos_kiosk/             # Raspberry Pi: Chromium-Kiosk + Heartbeat (ALAMOS AMweb)
│       └── xibo_kiosk/               # Raspberry Pi 3B+: NFS-Bilder-Slideshow-Kiosk (xibosignage)
└── argocd/
    ├── bootstrap/
    │   ├── root-applicationset.yaml  # Zwei Git-Generatoren: platform/* und workloads/*
    │   └── projects.yaml             # AppProjects "platform" und "workloads"
    └── apps/                         # Ein Ordner pro ArgoCD-Application, je Tier
        ├── platform/                 # AppProject "platform" — Schicht 3, siehe docs/b-kubernetes-gitops/b0020-argocd-projects.md
        │   ├── sealed-secrets/       # SealedSecrets-Controller
        │   ├── kubeseal-webgui/      # Sealed-Secrets-Verschlüsselungs-UI
        │   ├── monitoring/           # VictoriaMetrics + Grafana
        │   ├── logging/              # Log-Aggregation (VictoriaLogs)
        │   ├── gotify/               # Push-Notifications (Android)
        │   ├── gotify-bridge/        # Alertmanager → Gotify Webhook-Bridge
        │   ├── ntfy/                 # Push-Notifications (iOS + Android)
        │   ├── ntfy-bridge/          # Alertmanager → ntfy Webhook-Bridge
        │   ├── cloudflared/          # Cloudflare Tunnel — externe Erreichbarkeit
        │   ├── pihole/               # Netzwerkweites Werbeblocking (DNS-Filter vor der Fritz!Box)
        │   ├── coredns-custom/       # Zusätzliche CoreDNS-Zonen
        │   ├── nas-storage/          # NFS-Provisioner → StorageClass "nas" (/volume1)
        │   ├── immich-storage/       # Dedizierter NFS-Export für Immich (/volume2)
        │   ├── minio/                # S3-Artifact-Store für Argo Workflows
        │   ├── argo-workflows/       # Private CI/CD-Pipeline
        │   ├── semaphore/            # Ansible-Web-UI
        │   ├── headlamp/             # Kubernetes-Web-Dashboard
        │   └── traefik-config/       # Traefik-Zusatzkonfiguration
        └── workloads/                # AppProject "workloads" — Schicht 4, siehe docs/b-kubernetes-gitops/b0020-argocd-projects.md
            ├── example-whoami/
            ├── alamos-apager/        # Alarmmonitor-Kiosk-Verwaltung (ALAMOS AMweb)
            ├── mediamtx/             # Live-Streaming (RTMP/RTSP → HLS)
            ├── paperless-ngx/        # Dokumentenmanagement mit OCR
            ├── mealie/               # Rezeptverwaltung + Wochenplaner
            ├── n8n/                  # Low-Code-Automatisierung
            ├── uptime-kuma/          # Status-Seite und Service-Alerting
            ├── vaultwarden/          # Bitwarden-kompatibler Passwort-Manager
            ├── nextcloud/            # Datei-Sync, Kalender, Kontakte
            ├── immich/               # Foto-/Video-Backup vom Handy
            ├── wikijs/               # Wiki.js Team-Wiki
            ├── zammad/               # Helpdesk/Ticket-System
            ├── tinyteller/           # Kleine Diktier-/Story-App
            ├── wiki-docs-sync/       # CronJob: docs/ aus Git → Wiki.js, alle 15 Min.
            ├── github-release-watcher/  # CronJob: neue GitHub-Releases → Zammad-Ticket
            ├── carplay-api/          # Homeserver-Dashboard-API für die iOS-App (Verzeichnisname historisch aus der CarPlay-Vorversion)
            └── xibosignage/          # Xibo CMS: Medien-/Asset-Verwaltung für die Pi-Bilder-Slideshow

Monitoring

Ein schlanker VictoriaMetrics-+-Grafana-Stack lebt unter argocd/apps/platform/monitoring/ und wird automatisch von ArgoCD ausgerollt.

Stack-Details

Komponente	Detail
TSDB	VMSingle — 15 Tage Retention, 10 Gi `local-path`-PVC
Scrapers	VMAgent scrapet alle `VMServiceScrape`/`VMPodScrape` + Prometheus `ServiceMonitor`-CRDs
Host-Metriken	`prometheus-node-exporter` als DaemonSet auf dem Ubuntu-Host
Cluster-Metriken	kubelet/cAdvisor, kube-apiserver, kube-state-metrics, CoreDNS
Alerts	Default-kube-prometheus-Rules; Gotify- und ntfy-Alertmanager-Bridges
Dashboards	Node Exporter Full, VictoriaMetrics + Kubernetes Views von grafana.com

Grafana öffnen unter https://grafana.homeserver — Admin-Passwort abfragen:

kubectl -n monitoring get secret grafana-admin \
  -o jsonpath='{.data.admin-password}' | base64 -d; echo

Application hinzufügen (GitOps-Weg)

Erst entscheiden: Platform (Infrastruktur/Admin-Charakter) oder Workloads (echter Nutzerkreis) — siehe docs/b-kubernetes-gitops/b0020-argocd-projects.md.

mkdir -p argocd/apps/workloads/my-app
# Plain Kubernetes-YAML, kustomization.yaml oder ein Helm-Chart hineinlegen.

# my-app in argocd_workloads_apps (ansible/roles/argocd/defaults/main.yml) ergänzen,
# dann:
make render-bootstrap

git add argocd/apps/workloads/my-app/ ansible/roles/argocd/defaults/main.yml argocd/bootstrap/
git commit -m "feat(apps): add my-app"
git push

Innerhalb von ~3 Minuten erkennt ArgoCD das neue Verzeichnis, erstellt eine Application namens my-app im Namespace my-app (AppProject workloads) und synct sie. Details: docs/b-kubernetes-gitops/b0010-argocd.md, docs/b-kubernetes-gitops/b0020-argocd-projects.md

Service-URLs

Jeder Hostname trägt ein Tier-Label (tech = Infrastruktur/Admin, prod = Apps mit echtem Nutzerkreis) — Details und Begründung: docs/c-netzwerk-dns/c0040-domain-tiers.md.

Service	Tier	URL
Grafana	tech	https://grafana.tech.homeserver
ArgoCD	–	https://<server-ip>:30443
Headlamp	tech	https://headlamp.tech.homeserver
Semaphore	tech	https://semaphore.tech.homeserver
Gotify	tech	https://gotify.tech.homeserver
ntfy	tech	https://ntfy.tech.homeserver
Pi-hole	tech	https://pihole.tech.homeserver
Argo Workflows	tech	https://argo-workflows.tech.homeserver
MinIO Console	tech	https://minio.tech.homeserver
kubeseal-webgui	tech	https://kubeseal-webgui.tech.homeserver
Vaultwarden	tech (Ausnahme)	https://vault.tech.homeserver
Zammad	tech (Ausnahme)	https://zammad.tech.homeserver
Alarmmonitor (alamos-apager)	prod	https://alamos-apager.prod.homeserver
MediaMTX (Live-Stream-Playback)	prod	https://stream.prod.homeserver
Paperless-ngx	prod	https://paperless.prod.homeserver
Mealie	prod	https://mealie.prod.homeserver
n8n	prod	https://n8n.prod.homeserver
Uptime Kuma	prod	https://uptime-kuma.prod.homeserver
Nextcloud	prod	https://nextcloud.prod.homeserver
Immich	prod	https://immich.prod.homeserver
Wiki.js	prod	https://wiki.prod.homeserver
Xibo CMS (xibosignage)	prod	https://xibo.prod.homeserver

Zusätzlich zu den internen *.homeserver-URLs können ausgewählte Dienste über Cloudflare Tunnel öffentlich unter einer eigenen Domain erreichbar gemacht werden (z. B. https://wiki-prod.deine-domain.de — Bindestrich statt Punkt vor dem Tier, siehe docs/c-netzwerk-dns/c0040-domain-tiers.md) — ohne VPN, ohne offene Ports. Setup: docs/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md. Nextcloud, Immich und Vaultwarden sind zusätzlich unter https://nextcloud-prod.pke-lab.de, https://immich-prod.pke-lab.de bzw. https://vault-tech.pke-lab.de per Cloudflare Tunnel erreichbar (Details je Dienst in den verlinkten Docs unten) — bei Immich nötig für Handy-Auto-Backup unterwegs. Der Live-Stream ist zusätzlich unter https://stream-prod.pke-lab.de erreichbar, abgesichert per mediamtx-eigenem HTTP-Basic-Login — kein externer Identity-Provider, kein Cloudflare-Zero-Trust-Konto nötig. Details: docs/3-apps-workloads/30040-mediamtx.md.

Networking & Security

Prinzip	Umsetzung
Keine öffentlichen Ports	Zugriff ausschließlich über LAN, Tailscale-VPN oder gezielt per Cloudflare Tunnel (ausgehende Verbindung, kein Port-Forwarding)
UFW-Firewall	Erlaubt nur SSH, HTTP/HTTPS, k3s-API, ArgoCD-NodePort (HTTPS-only), Flannel, Tailscale-UDP
Opt-in externe Erreichbarkeit	Nur explizit in `argocd/apps/platform/cloudflared/values.yaml` eingetragene Dienste sind öffentlich erreichbar, alles andere bleibt intern
Brute-Force-Schutz	CrowdSec beobachtet SSH- und Traefik-Logs und lässt einen Firewall-Bouncer auffällige IPs sperren, siehe docs/d-sicherheit/d0020-crowdsec.md
Ansible-Vault	Sensitive Secrets verschlüsselt at rest
ArgoCD Read-only	Hat ausschließlich Read-Access auf das Git-Repo
ArgoCD-AppProjects	Zwei Projects (`platform` / `workloads`) trennen Infrastruktur-Apps von Anwendungen mit echtem Nutzerkreis — jede App darf nur in ihren eigenen Namespace deployen, siehe docs/b-kubernetes-gitops/b0020-argocd-projects.md

Firewall-Ports

Port	Protokoll	Scope	Zweck
22	TCP	LAN + Tailnet	SSH
53	UDP+TCP	LAN + Tailnet	dnsmasq Split-DNS für `*.homeserver`
80	TCP	LAN + Tailnet	Traefik HTTP
443	TCP	LAN + Tailnet	Traefik HTTPS
6443	TCP	LAN + Tailnet	k3s-API
30443	TCP	LAN + Tailnet	ArgoCD-UI (HTTPS)
41641	UDP	Internet	Tailscale-WireGuard

Vollständige Architektur: docs/a-betriebssystem/a0010-overview.md

Dokumentation

Alle Docs liegen unter docs/, sortiert in 9 Kategorie-Unterordner. Jede Datei trägt eine 5-stellige Hex-ID (erstes Zeichen = Kategorie) — Details und Konventionen für neue Docs: docs/TEMPLATE.md.

Betriebssystem & Grundlagen (`a-betriebssystem/`)

Dokument	Inhalt
Ubuntu-Server-Installation	ISO, USB-Stick, Installer, erster Boot
Architektur-Überblick	Komponenten und Traffic-Flows
Voraussetzungen	Was vor dem Ansible-Run nötig ist
Installationsleitfaden	Vollständiger Step-by-Step-Walkthrough
Troubleshooting	Diagnose-Playbook für häufige Probleme

Kubernetes & GitOps (`b-kubernetes-gitops/`)

Dokument	Inhalt
k3s-Referenz	Config, kubectl-Cheatsheet, Upgrades
ArgoCD-GitOps	App-Workflow, CLI, Sync-Policies
ArgoCD-Projects	Platform/Workloads-AppProject-Trennung, Ordnerstruktur, neue App hinzufügen
Semaphore-UI	Web-UI zum Ausführen von Playbooks
Autoskalierung (HPA)	Welche Apps per HorizontalPodAutoscaler mitskalieren, welche bewusst nicht, und mit welchen Schwellenwerten

Netzwerk & DNS (`c-netzwerk-dns/`)

Dokument	Inhalt
DNS-Architektur	Warum der Home-Server NICHT dein LAN-DNS ist
Tailscale-VPN	Auth-Keys, MagicDNS, Subnet-Routes
Pi-hole	Netzwerkweites Werbeblocking als DNS-Filter vor der Fritz!Box — kein Router-Eingriff nötig
Port-Übersicht	Interner Service-Port, LAN- und externe Erreichbarkeit für jede App
Domain-Tiers	dev/tech/prod-URL-Konvention (`app.tier.homeserver`), Ausnahmen, Cross-App-Referenzen

Externe Erreichbarkeit (`e-externe-erreichbarkeit/`)

Dokument	Inhalt
Cloudflare Tunnel — Setup	Externe Erreichbarkeit ohne VPN: Konzept, Tunnel-Einrichtung, Absicherung
Cloudflare Tunnel — Deploy	Rollout, neuen Dienst freigeben, Rotation, Troubleshooting

Sicherheit (`d-sicherheit/`)

Dokument	Inhalt
Incident-Report 12.08.2026	Postmortem: ApplicationSet-Migration löschte versehentlich 32 Apps, Ursache + Gegenmaßnahmen
Security-Härtung — Roadmap	Phasenplan der Security-Härtung nach dem Incident vom 12.08.2026
CrowdSec	Brute-Force-Schutz für SSH und Traefik, Firewall-Bouncer, Whitelist für LAN/Tailnet
Cluster-NetworkPolicies	NetworkPolicies je Namespace, Default-Deny + explizite Ausnahmen (Härtung Phase 3)
Internes TLS	cert-manager + eigene CA für HTTPS auf `*.homeserver` (Härtung Phase 5)
Secrets-Encryption + Audit-Log	k3s Secrets-at-Rest-Verschlüsselung + API-Audit-Log (Härtung Phase 4)
Secrets-Rotation-Checkliste	Checkliste zur regelmäßigen Rotation aller Cluster-Secrets (Härtung Phase 7)

CI/CD & Automatisierung (`f-cicd-automatisierung/`)

Dokument	Inhalt
Argo Workflows	Private CI/CD-Pipeline mit MinIO-Artifact-Store
Renovate	Automatische Update-PRs für Helm-Chart-Versionen und Image-Tags
Release-Automatisierung	GitHub Release + Changelog bei jedem Merge auf `main` via semantic-release
GitHub Release Watcher	Neue GitHub-Releases erkennen und per Zammad-Ticket eine E-Mail-Benachrichtigung auslösen
GitLab-Mirror	Vollspiegelung (alle Branches + Tags) zu GitLab als Redundanz für den Fall eines GitHub-Ausfalls

Benachrichtigungen (`1-benachrichtigungen/`)

Dokument	Inhalt
Gotify-Push	Self-hosted Push-Notifications aus dem Stack
ntfy iOS-Push	Self-hosted ntfy mit iOS APNs-Relay

Betrieb & Hardware (`2-betrieb-hardware/`)

Dokument	Inhalt
NAS-Storage	NFS-StorageClass gegen die UGREEN NAS (RAID1), Migration einzelner Apps von local-path
NAS-Backup	Externe USB-Platte am NAS: regelmäßige restic-Backups von volume1 + volume2
Cluster Power Manager	worker-0/worker-1 per Wake-on-LAN je nach Homeserver-Last automatisch dazu- und wieder abschalten
Nightly Worker Update	worker-0/worker-1 nachts um 01:00 Uhr per Wake-on-LAN wecken, apt-Update fahren (max. 20 Min.), wieder herunterfahren
Drucker (CUPS)	Samsung Xpress M2026 per USB am Homeserver, Freigabe im Heimnetz + Tailnet via IPP/AirPrint

Apps & Workloads (`3-apps-workloads/`)

Dokument	Inhalt
Zammad	Helpdesk-/Ticket-System, u. a. Ziel für github-release-watcher-Benachrichtigungen
Alarmmonitor-Kiosks	Raspberry-Pi-Kiosks für ALAMOS AMweb, zentral verwaltet
Vereinsheim-Alarmmonitor	Banana-Pi-Kiosk fürs Vereinsheim, Alarmstatus-Anzeige + Heartbeat-Monitoring
Wiki.js	Team-Wiki, `docs/` wird per wiki-docs-sync automatisch gespiegelt
MediaMTX Live-Streaming	RTMP/RTSP-Ingest → HLS, Publish- und Zuschauer-Autorisierung über mediamtx' eingebaute interne Benutzerverwaltung (HTTP Basic Auth)
Paperless-ngx	Dokumentenmanagement mit OCR — Briefe, Rechnungen, Verträge scannen und durchsuchen
Mealie	Rezeptverwaltung + Wochenplaner mit URL-Import
n8n	Low-Code-Automatisierung — Dienste verknüpfen ohne Programmieren
Uptime Kuma	Status-Seite und Alerting für alle Dienste
Rhein-Dashboard	Grafana: Pegelonline, DWD-Warnungen, ELWIS, Hochwasservorhersage RLP
Vaultwarden	Bitwarden-kompatibler Passwort-Manager für Browser/Mobile-Clients
Nextcloud	Datei-Sync, Kalender, Kontakte
Immich	Foto-/Video-Backup vom Handy inkl. Gesichtserkennung, eigener NAS-Storage-Export
Homeserver-Dashboard-API	Go/Gin-API + power-agent für die reine iOS-App Homeserver Dashboard (Metriken, Alerts, Status, Helligkeit, Wake/Shutdown)
xibosignage	Xibo CMS + Bilder-Slideshow auf Raspberry Pi 3B+, n8n-Workflow für automatisches Einspielen
pacman — Besuchertracking	IP/GeoIP-Besucher-Tracking-Demo für die IT-Security-Schulung

MIT — siehe LICENSE · Made with ☕ & GitOps

Navigation Menu

Repository files navigation

⚡ TL;DR

Was du bekommst

Quickstart (5 Schritte)

Repository-Layout

Monitoring

Application hinzufügen (GitOps-Weg)

Service-URLs

Networking & Security

Dokumentation

Betriebssystem & Grundlagen (`a-betriebssystem/`)

Kubernetes & GitOps (`b-kubernetes-gitops/`)

Netzwerk & DNS (`c-netzwerk-dns/`)

Externe Erreichbarkeit (`e-externe-erreichbarkeit/`)

Sicherheit (`d-sicherheit/`)

CI/CD & Automatisierung (`f-cicd-automatisierung/`)

Benachrichtigungen (`1-benachrichtigungen/`)

Betrieb & Hardware (`2-betrieb-hardware/`)

Apps & Workloads (`3-apps-workloads/`)

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.idea		.idea
ansible		ansible
argocd		argocd
docs		docs
ios		ios
scripts		scripts
.DS_Store		.DS_Store
.gitignore		.gitignore
.releaserc.json		.releaserc.json
IdeasToDeploy.md		IdeasToDeploy.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
renovate.json		renovate.json
test_creates.yml		test_creates.yml
yumi_py-1.0.5		yumi_py-1.0.5

Latest commit

History

Folders and files

Repository files navigation

⚡ TL;DR

Was du bekommst

Quickstart (5 Schritte)

Repository-Layout

Monitoring

Application hinzufügen (GitOps-Weg)

Service-URLs

Networking & Security

Dokumentation

Betriebssystem & Grundlagen (a-betriebssystem/)

Kubernetes & GitOps (b-kubernetes-gitops/)

Netzwerk & DNS (c-netzwerk-dns/)

Externe Erreichbarkeit (e-externe-erreichbarkeit/)

Sicherheit (d-sicherheit/)

CI/CD & Automatisierung (f-cicd-automatisierung/)

Benachrichtigungen (1-benachrichtigungen/)

Betrieb & Hardware (2-betrieb-hardware/)

Apps & Workloads (3-apps-workloads/)

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Betriebssystem & Grundlagen (`a-betriebssystem/`)

Kubernetes & GitOps (`b-kubernetes-gitops/`)

Netzwerk & DNS (`c-netzwerk-dns/`)

Externe Erreichbarkeit (`e-externe-erreichbarkeit/`)

Sicherheit (`d-sicherheit/`)

CI/CD & Automatisierung (`f-cicd-automatisierung/`)

Benachrichtigungen (`1-benachrichtigungen/`)

Betrieb & Hardware (`2-betrieb-hardware/`)

Apps & Workloads (`3-apps-workloads/`)