From ccf6856f423dd279049dbc2a22bbddbafe39856b Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Tue, 28 Jul 2026 12:00:00 +0000 Subject: [PATCH] docs: bring top-level README up to date README described only the initial v0.1.0-era bootstrap - no mention of Authentik, coturn/TURN, monitoring, NetworkPolicies, backups, or the Element Web/Call forks, all of which have been live for months. Also fixed: broken TOC links (pointed to Google search instead of anchors), stale mas-secrets.sops.yaml / ess-mas-custom-secrets references (actual names are mas-secret.yaml / ess-mas-values-secret). Added pointers to CLAUDE.md, docs/TASKS.md, Gitea Releases (new SemVer scheme), the wiki, and deployment guides, plus a note recommending the devcontainer as the primary way to get local tooling. Co-Authored-By: Claude Sonnet 5 --- README.md | 59 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 45 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index abc1d1b..6fd94e3 100644 --- a/README.md +++ b/README.md @@ -4,18 +4,23 @@ Dieses Repository enthält die Infrastruktur-as-Code (IaC) für den Matrix-Homes ## 📑 Inhaltsverzeichnis -1. [Voraussetzungen & Lokale Tools](https://www.google.com/search?q=%231-voraussetzungen--lokale-tools) -2. [Architektur & Logik des Stacks](https://www.google.com/search?q=%232-architektur--logik-des-stacks) -3. [Aufbau des Repositories](https://www.google.com/search?q=%233-aufbau-des-repositories) -4. [Das Deployment (Aktueller Stand)](https://www.google.com/search?q=%234-das-deployment-aktueller-stand) -5. [Nützliche Befehle](https://www.google.com/search?q=%235-n%C3%BCtzliche-befehle) -6. [Troubleshooting & Known Issues](https://www.google.com/search?q=%236-troubleshooting--known-issues) +1. [Voraussetzungen & Lokale Tools](#1-voraussetzungen--lokale-tools) +2. [Architektur & Logik des Stacks](#2-architektur--logik-des-stacks) +3. [Aufbau des Repositories](#3-aufbau-des-repositories) +4. [Das Deployment (Aktueller Stand)](#4-das-deployment-aktueller-stand) +5. [Nützliche Befehle](#5-nützliche-befehle) +6. [Troubleshooting & Known Issues](#6-troubleshooting--known-issues) +7. [Weitere Ressourcen](#7-weitere-ressourcen) ----- ## 1\. Voraussetzungen & Lokale Tools -Um mit diesem Stack zu interagieren (Konfigurationen anzupassen, Secrets zu verschlüsseln, Fehler zu suchen), müssen folgende Tools lokal installiert sein: +**Empfohlen: `.devcontainer/` nutzen** ("Reopen in Container" in VS Code, oder `docker build` ++ `docker run` manuell, siehe [`.devcontainer/README.md`](.devcontainer/README.md)) - bringt +alle unten genannten Tools bereits fertig eingerichtet mit, ohne sie lokal zu installieren. + +Alternativ, um mit diesem Stack zu interagieren (Konfigurationen anzupassen, Secrets zu verschlüsseln, Fehler zu suchen), müssen folgende Tools lokal installiert sein: ### 🛠️ Benötigte CLI-Tools @@ -70,9 +75,10 @@ Das Setup basiert auf einer modernen, modularen GitOps-Architektur: * **K3s**: Die leichtgewichtige Kubernetes-Distribution, die als Fundament dient. * **FluxCD**: Der GitOps-Controller. Er überwacht dieses Git-Repository. Ändert sich hier eine Datei, wendet Flux die Änderung automatisch im Cluster an. - * **SOPS**: Erlaubt es, Passwörter (z.B. SMTP) verschlüsselt in Git zu speichern. Flux entschlüsselt diese "on the fly" im Cluster. + * **SOPS + age**: Erlaubt es, Secrets verschlüsselt in Git zu speichern. Flux entschlüsselt diese "on the fly" im Cluster. Mehrere Secrets nutzen zusätzlich einen zweiten, eng gescopten age-Key für automatisierte Rotation (siehe coturn TURN-Secret unten). * **Traefik**: Der Ingress-Controller (Standard bei K3s). Er leitet Traffic von Port 80/443 an die richtigen internen Pods weiter. * **Cert-Manager**: Spricht mit Let's Encrypt und stellt automatisch gültige TLS-Zertifikate für alle Ingress-Routen aus. + * **NetworkPolicies**: Default-Deny Ingress für die `matrix`- und `authentik`-Namespaces, mit expliziten Allow-Regeln pro Komponente (`apps/production/networkpolicy.yaml`, `apps/authentik/networkpolicy.yaml`). ### Matrix Stack (ESS Community v26.4.0) @@ -80,10 +86,17 @@ Die Suite ist ein "Umbrella Chart", das aus mehreren Microservices besteht: * **Synapse (`matrix.`):** Das eigentliche Backend (Homeserver) für die Chat-Nachrichten. * **Matrix Authentication Service (MAS) (`account.`):** Der OIDC-basierte Login-Server. Zwingend erforderlich für moderne Matrix-Clients. - * **Element Web (`domain.tld`):** Der Web-Client für die Endnutzer. - * **Matrix RTC (`mrtc.`):** Die SFU (Selective Forwarding Unit) für Audio-/Video-Calls. + * **Element Web (`domain.tld`):** Eigener Fork (`sorb/threadnet-web`) des Web-Clients für die Endnutzer - Custom Themes, Element Desktop Setup-Seiten, Element-Call-Anpassungen. + * **Matrix RTC (`mrtc.`):** Die SFU (Selective Forwarding Unit) für Audio-/Video-Calls, mit eigenem Element-Call-Fork (`sorb/threadnet-call`) für höhere Video-Defaults (bis 1440p/60fps). + * **coturn:** TURN/STUN-Server für WebRTC hinter NAT (`hostNetwork: true`, außerhalb der NetworkPolicy-Kontrolle, stattdessen über die Hetzner Cloud Firewall abgesichert). Shared Secret wird monatlich automatisiert rotiert. * **PostgreSQL:** Die relationale Datenbank für Synapse und MAS. +### Identity & Observability + + * **Authentik** (`auth.`, `account.`): OIDC-Identity-Provider für Matrix-Enrollment, Passwort-Recovery und optionales 2FA/Passkey. Flows/Provider/Application deklarativ als Authentik-Blueprints erfasst (`apps/authentik/authentik-blueprints.yaml`), nicht nur in der UI geklickt. + * **Monitoring**: Grafana Alloy sammelt Metriken/Logs, Remote-Write zu einem externen Prometheus/Loki-Stack. + * **Backups**: Nächtliche, verschlüsselte & deduplizierte Borg-Backups (Postgres-Dumps + Synapse-`media_store`) zu einer Hetzner Storage Box, getrennt nach Namespace, mit eigenen Repos/Passphrasen. + ----- ## 3\. Aufbau des Repositories @@ -106,9 +119,14 @@ gitops/ │ └── custom-configs/ # Eigene Anpassungen (Themes, Logging) │ ├── synapse-values.yaml # Als ConfigMap │ ├── element-values.yaml # Als ConfigMap -│ └── mas-secrets.sops.yaml # Als verschlüsseltes SOPS-Secret +│ └── mas-secret.yaml # Als verschlüsseltes SOPS-Secret ``` +Weitere Secret-Dateien liegen direkt unter `apps/production/` bzw. `apps/authentik/` +(z.B. `coturn-secret.yaml`, `synapse-turn-secret.yaml`, `synapse-backup-secret.yaml`, +`authentik-backup-secret.yaml`) - jede einzeln SOPS-verschlüsselt, nicht in `custom-configs/` +gebündelt. + **Abhängigkeits-Logik:** Flux installiert erst `infra-apps` (damit Namespaces und Repositories existieren) und danach `production-apps` (das eigentliche ESS-Chart). ----- @@ -156,7 +174,10 @@ spec: name: ess-synapse-custom valuesKey: values.yaml - kind: Secret - name: ess-mas-custom-secrets + name: ess-mas-values-secret + valuesKey: values.yaml + - kind: Secret + name: synapse-turn-secret valuesKey: values.yaml values: serverName: axion1337.chat @@ -216,7 +237,7 @@ kubectl describe challenge -n matrix Um ein Passwort im GitOps-Repo zu ändern, editiert man die verschlüsselte Datei direkt via SOPS (sie wird transparent entschlüsselt und beim Speichern wieder verschlüsselt): ```bash -sops apps/production/custom-configs/mas-secrets.sops.yaml +sops apps/production/custom-configs/mas-secret.yaml ``` ----- @@ -244,4 +265,14 @@ sops apps/production/custom-configs/mas-secrets.sops.yaml ### Issue 4: Fehlende Zertifikate (`No resources found`) * **Ursache:** Manuelle Kustomize-Patches kollidieren mit dem Helm-Chart. - * **Lösung:** Manuelle Patches löschen und das native Feature des Charts nutzen: `certManager: true` auf der obersten (Root-)Ebene der `values` setzen. Das Chart erstellt daraufhin die korrekten Ingress-Annotations und Secrets von selbst. \ No newline at end of file + * **Lösung:** Manuelle Patches löschen und das native Feature des Charts nutzen: `certManager: true` auf der obersten (Root-)Ebene der `values` setzen. Das Chart erstellt daraufhin die korrekten Ingress-Annotations und Secrets von selbst. + +----- + +## 7\. Weitere Ressourcen + + * **`CLAUDE.md`** (`prod/`): Technische Referenz für KI-gestützte Arbeit an diesem Repo - Architektur, bekannte Chart-Quirks, Troubleshooting-Checkliste. + * **`docs/TASKS.md`**: Backlog-Pointer zu den [Gitea Issues](https://rohana.axion1337.de/sorb/axion1337.chat-gitops/issues) - Details werden nicht mehr doppelt gepflegt. + * **[Gitea Releases](https://rohana.axion1337.de/sorb/axion1337.chat-gitops/releases)**: Versionshistorie (SemVer, `vMAJOR.MINOR.PATCH` als Änderungsgrößen-Konvention, kein Kompatibilitätsvertrag - siehe [[00-TASKS]] Wiki für die Konvention). + * **[Wiki](https://rohana.axion1337.de/sorb/axion1337.chat-gitops/wiki)**: Ausführliche Historie, Incident-Notizen, Setup-Guides pro Komponente. + * **`docs/deployment-guides/`**: Detaillierte Guides für TURN-Server, Authentik, Monitoring, Element-Customization, Room-Policies. \ No newline at end of file