updates

Repo sauber machen

docs/MIGRATION_LOG.md

@@ -1,127 +1,50 @@
-# Migration Log — Homelab GitOps
+# Migration Log - Homelab GitOps
 
-Dieses Dokument verfolgt den Fortschritt der Migration hin zu einem vollständigen GitOps-Setup (Gitea + Komodo).
+Dieses Dokument ist nur noch ein historischer Verlauf. Der aktuelle operative Ablauf steht in `docs/WORKFLOW.md`, das Zielbild in `HOMELAB_ARCHITECTURE_MASTER_V2.md`.
 
-## Status-Legende
-- ⏳ = geplant
-- 🔄 = in Bearbeitung
-- ✅ = abgeschlossen
-- ⚠️ = Problem / prüfen
+## Aktueller Endstand
+
+- Gitea Online ist der verbindliche Sollzustand.
+- Komodo ist der einzige produktive Stack-Manager.
+- Portainer CE ist entfernt.
+- Firefly, Firefly-Fints und Semaphore sind entfernt.
+- Borg UI ist produktiv, Dump-Automatisierung laeuft host-seitig und ein Restore-Smoke-Test wurde erfolgreich durchgefuehrt.
+- GitHub Desktop ist der bevorzugte lokale Workflow fuer `Fetch`, `Pull`, `Commit` und `Push`.
 
 ---
 
-## Sprint 1 — Quick Wins + Vaultwarden ✅
+## Historische Meilensteine
 
-| Service | Status | Ergebnis |
-|---|---|---|
-| Vaultwarden | ✅ | Git-Stack, Traefik, `ADMIN_TOKEN_FILE`, Port entfernt |
-| PostgreSQL 17 | ✅ | `backend_net`, Port entfernt, `POSTGRES_PASSWORD_FILE` |
+### 2026-03-28 - GitOps-Konsolidierung
+
+- Komodo als primaeren Stack-Manager eingefuehrt.
+- Portainer aus dem Zielbild herausgenommen.
+- Traefik auf 100% Docker-Labels konsolidiert.
+- `diun` entfernt; Update-Monitoring wird ueber Komodo abgedeckt.
+
+### 2026-03-29 - Portainer abgeschaltet
+
+- Portainer CE aus dem produktiven Betrieb entfernt.
+- Komodo als alleinigen Stack-Manager festgezogen.
+
+### 2026-04-13 bis 2026-04-15 - Borg-Rollout abgeschlossen
+
+- `critical_infra` erfolgreich nach Borg gesichert.
+- Pre-Backup-Dumps host-seitig ueber Unraid User Scripts etabliert.
+- Dump-Zielpfad auf `/mnt/user/backups/borg/dumps` umgestellt.
+- Restore-Smoke-Test fuer `postgresql17-globals.sql` und `gitea.db` erfolgreich nachgewiesen.
+- Monitoring fuer Borg ueber `ntfy` und Uptime Kuma eingerichtet.
+
+### 2026-04-15 - Repo- und Betriebsbereinigung
+
+- Firefly, Firefly-Fints und Semaphore aus Repo und Homelab entfernt.
+- GitHub Desktop als Standard-Workflow fuer den lokalen Sync festgelegt.
 
 ---
 
-## Sprint 2 — postgresql17 + diun/gotify ✅
+## Dauerhafte Learnings
 
-| Service | Status | Ergebnis |
-|---|---|---|
-| postgresql17 | ✅ | Git-Stack abgeschlossen |
-| gotify | ✅ | `GOTIFY_DEFAULTUSER_PASS_FILE`, Traefik aktiv |
-| diun | ✅ | **Entfernt** (2026-03-28) — Update-Monitoring via Komodo |
-
----
-
-## Sprint 3 — mealie + mail-archiver ✅
-
-| Service | Status | Ergebnis |
-|---|---|---|
-| mealie | ✅ | internes Netz (`mealie_internal`), Port entfernt, Traefik aktiv |
-| mealie-postgres | ✅ | nur internes Netz, isoliert |
-| mail-archiver | ✅ | `frontend_net` + `backend_net` (Hybrid), Portainer ENV |
-
----
-
-## Sprint 4 — Frontend-Stack + Traefik Cleanup + Komodo ✅
-
-| Service | Status | Ergebnis |
-|---|---|---|
-| paperless-ngx | ✅ | Traefik aktiv, tls=true, Port entfernt |
-| Paperless-AI | ✅ | Traefik aktiv |
-| PortainerCE | ✅ | Traefik + Middleware, direkte Ports entfernt — **Legacy**, wird in Sprint 5 abgeschaltet |
-| Dozzle | ✅ | Traefik + Middleware, direkte Ports entfernt |
-| dashdot | ✅ | Traefik + Middleware, direkte Ports entfernt |
-| scrutiny | ✅ | `frontend_net`, Traefik + Middleware, als Git-Stack migriert |
-| filebrowser | ✅ | `frontend_net`, Traefik + Middleware, Port entfernt |
-| gitea | ✅ | Traefik aktiv, SSH-Port 222 bleibt (dokumentierte Ausnahme) |
-| UptimeKuma | ✅ | Traefik aktiv, Port entfernt, Middleware aktiv |
-| backrest | ✅ | `traefik.docker.network=frontend_net` korrigiert (war `backend_net`) |
-| **Komodo** | ✅ | **Eingeführt als primärer GitOps-Stack-Manager** |
-| **Traefik File-Provider** | ✅ | `immich.yml`, `gitea.yml`, `mealie.yml`, `scrutiny.yml`, `vaultwarden.yml.bak` gelöscht — Traefik läuft jetzt 100% auf Docker-Labels |
-| **immich Bad Gateway** | ✅ | Traefik nutzt jetzt `immich@docker` statt `immich@file` |
-
----
-
-## Sprint 5 — Compose-Migration Dockerman-Container 🔄 In Bearbeitung
-
-| Service | Status | Ziel |
-|---|---|---|
-| luckyBackup | ⏳ | `frontend_net`, Traefik, Middleware, Port entfernen |
-| Stash | ⏳ | Compose-Migration |
-| Tailscale-Docker | ⏳ | Compose-Migration, `host`-Netz bleibt (dokumentiert) |
-| netdata | ⏳ | Compose-Migration, leere CLAIM-Vars entfernen |
-| Plex-Media-Server | ⏳ | Compose-Migration, `host`-Netz bleibt (Discovery) |
-| Pi-hole | ⏳ | zuletzt konsolidieren |
-| **PortainerCE** | ⏳ | **abschalten** nach vollständiger Komodo-Übernahme |
-
----
-
-## Sprint 6 — Hardening / Secrets / Volumes ⏳ Offen
-
-| Aufgabe | Status |
-|---|---|
-| `immich_default` — `internal: true` setzen | ⏳ |
-| `immich_redis` — anonymes Volume → named volume | ⏳ |
-| `immich_server` — anonymes Volume prüfen | ⏳ |
-| `backrest` — rw-Mount auf konkrete Pfade einschränken | ⏳ |
-| `filebrowser` — Mount-Pfad einschränken | ⏳ |
-| Redis — named volume | ⏳ |
-
----
-
-## Sprint 8 — Borg UI / BorgBase 🔄 In Bearbeitung
-
-| Service | Status | Ergebnis |
-|---|---|---|
-| Borg UI | 🔄 | Git-Stack unter `ops/borg-ui/` angelegt; Traefik + Middleware, keine Host-Ports, minimale Source-Mounts (`/mnt/user/appdata` read-only) |
-| BorgBase-Anbindung | ⏳ | Nach Deploy: SSH-Key aus Borg UI in BorgBase hinterlegen, Repo anlegen, `repokey-blake2` initialisieren, Job/Schedule im UI setzen |
-
----
-
-## Wichtige Entscheidungen & Learnings
-
-### Komodo ersetzt Portainer (2026-03-28)
-Komodo ist der primäre GitOps-Stack-Manager. Stacks werden via Gitea synchronisiert und über Komodo deployed. Portainer CE läuft noch als Legacy-UI.
-
-### Traefik File-Provider Cleanup (2026-03-28)
-Statische File-Provider-Configs hatten `@file`-Routen, die mit `@docker`-Routen konkurrierten. In Traefik v3 gewinnt der File-Provider → Immich wurde auf falsche IP geroutet (Bad Gateway). Nach Löschen der statischen Configs läuft alles über Docker-Labels.
-
-### diun entfernt (2026-03-28)
-Update-Monitoring kann über Komodo's eingebaute Update-Notifications abgedeckt werden.
-
-### Portainer + Git + env_file
-Host-Pfade (`/mnt/...`) sind in Portainer/Komodo Git-Stacks nicht verfügbar → `env_file` ungeeignet. Lösung: Stack Environment Variables mit `${VARIABLE}` in der Compose.
-
-### `_FILE` Support ist nicht universell
-| Container | `_FILE` Support |
-|---|---|
-| Vaultwarden | ✅ ja |
-| PostgreSQL | ✅ ja |
-| Gotify | ✅ ja |
-| code-server | ✅ ja |
-| Mealie | ❌ nein → Stack ENV |
-| paperless-ngx | ❌ nein für DB-Pass → Stack ENV |
-
----
-
-## Notizen
-- Keine Migration ohne Test
-- Immer nur einen Service gleichzeitig
-- Rollback muss jederzeit möglich sein
+- Kein Live-Editing in Komodo; Git gewinnt immer gegen manuelle Drift.
+- Webhooks koennen nach einem Push sofort einen Deploy ausloesen.
+- Rollback soll bevorzugt ueber saubere Git-Commits und bekannte Good States erfolgen, nicht ueber History-Rewrites auf `master`.
+- Doku soll Endzustaende beschreiben, nicht veraltete Zwischenstaende konservieren.

docs/ROLLBACK.md

@@ -1,108 +1,102 @@
-# Rollback Guide — Homelab
+# Rollback Guide - Homelab
 
-Dieses Dokument beschreibt, wie Änderungen rückgängig gemacht werden können.
+Dieses Dokument beschreibt den sicheren Rueckweg im aktuellen GitOps-Betrieb.
 
 ---
 
 ## Grundprinzip
 
-Jede Änderung muss rückrollbar sein.
+Rollback bedeutet in diesem Setup:
+
+- auf einen bekannten funktionierenden Git-Stand zurueckgehen
+- den Zustand sauber nach Gitea bringen
+- Komodo gezielt auf diesen Stand deployen lassen
+
+`master` wird dabei **nicht** per `push --force` umgeschrieben, solange es keinen ausdruecklich abgestimmten Ausnahmefall gibt.
 
 ---
 
-## Standard-Rollback (Git)
+## Standard-Rollback ueber Git
 
-### Letzten Stand anzeigen
-```bash
-git log --oneline
-```
+Bevorzugter Weg:
 
-### Auf vorherigen Stand zurücksetzen
-```bash
-git reset --hard <commit-id>
-git push --force
-```
+1. den letzten funktionierenden Commit identifizieren
+2. lokal einen sauberen Ruecknahme-Commit erzeugen (`git revert` oder gezielte Rueckaenderung)
+3. nach Gitea pushen
+4. Komodo-Deploy und Funktion pruefen
+
+Warum so:
+
+- die Historie bleibt nachvollziehbar
+- Webhooks und Team-Workflow bleiben stabil
+- es gibt keinen verdeckten History-Rewrite auf `master`
 
 ---
 
-## Rollback über Komodo (primär)
+## Rollback ueber Komodo
 
-1. Stack in Komodo öffnen
-2. „Redeploy" auswählen
-3. vorherigen Commit im Gitea-Repo referenzieren
-4. Deploy ausführen
+Komodo ist der operative Deploy-Consumer, nicht die Quelle der Wahrheit.
+
+Vorgehen:
+
+1. Git-Stand in Gitea auf den gewuenschten Sollzustand bringen
+2. betroffenen Stack in Komodo oeffnen
+3. Redeploy auf Basis dieses Git-Stands ausloesen
+4. Logs, Health und Erreichbarkeit pruefen
+
+Wichtig:
+
+- kein manuelles Ueberschreiben im Komodo-Web-Editor
+- wenn Komodo und Git abweichen, gewinnt Git
 
 ---
 
-## Rollback über Portainer (Legacy)
+## Ausnahmefall: harter Git-Rollback
 
-> ⚠️ Portainer CE ist in Ablösung durch Komodo (Sprint 5). Bis zur Abschaltung weiterhin nutzbar.
+Ein `git reset --hard` mit anschliessendem erzwungenem Push auf `master` ist **kein Standardverfahren**.
 
-1. Stack öffnen
-2. „Redeploy" auswählen
-3. vorherigen Commit verwenden (bei Git-Stacks)
+Das kommt nur in Frage, wenn:
+
+- der Fall bewusst abgestimmt ist
+- klar ist, welche Webhook-/Deploy-Seiteneffekte ausgeloest werden
+- keine sauberere Ruecknahme ueber `git revert` mehr sinnvoll ist
 
 ---
 
-## Container-Rollback
+## Borg / Backup-bezogener Rollback
 
-Wenn ein neuer Stack Probleme macht:
+Bei Problemen mit Borg UI oder Dump-Automatisierung:
 
-1. neuen Container stoppen
-2. alten Container wieder starten
-3. Logs prüfen
-
-### Borg UI / BorgBase
-
-Bei Problemen mit `ops/borg-ui/docker-compose.yml`:
-
-1. in Gitea auf den letzten funktionierenden Commit zurückgehen
-2. Stack in Komodo auf diesen Commit redeployen
-3. Persistenz unter `/mnt/user/appdata/borg-ui/` unverändert lassen
-4. BorgBase-Repository nicht löschen; Remote-Archive bleiben davon unberührt
-5. falls nötig, Restore zunächst aus `/mnt/user/appdata/borg-ui/restore/` testen statt direkt in Produktivpfade zurückzuschreiben
+1. auf den letzten funktionierenden Git-Stand zurueckgehen
+2. `borg-ui` ueber Komodo redeployen
+3. Persistenz unter `/mnt/user/appdata/borg-ui/` und `/mnt/user/backups/borg/dumps/` nicht blind loeschen
+4. Restore zuerst in einen Testpfad schreiben, nicht direkt in Produktivpfade
 
 ---
 
-## Datenbank-Rollback
+## Daten-Rollback
 
-### Backup vorhanden (empfohlen über backrest)
-Restore durchführen
+Bevorzugte Quellen:
+
+- Borg-Restore
+- erzeugte PostgreSQL-/MariaDB-Dumps
+- bekannte Appdata-Snapshots
+
+Beispiele:
 
-### Manuelle Sicherung
 ```bash
 cp -r /mnt/user/appdata/<service> /mnt/user/backup/
 ```
 
-### PostgreSQL-Dump
 ```bash
 pg_dumpall > /mnt/user/backup/pg_dump_$(date +%Y%m%d).sql
 ```
 
 ---
 
-## Best Practices
+## Betriebsregeln
 
-- Immer nur **eine Änderung gleichzeitig**
-- Vor jeder Änderung prüfen:
-  - läuft Backup?
-  - ist der aktuelle Zustand stabil?
-- Nach jeder Änderung:
-  - Funktion testen
-  - Logs prüfen
-  - Migration im `MIGRATION_LOG.md` dokumentieren
-
----
-
-## Notfallregel
-
-Wenn etwas unklar ist:
-- NICHT weiter ändern
-- aktuellen Zustand analysieren
-- gezielt und kontrolliert eingreifen
-
----
-
-## Ziel
-
-Rollback muss jederzeit möglich sein, ohne Datenverlust und ohne unnötige Downtime.
+- immer nur eine aenderungsrelevante Massnahme gleichzeitig
+- vor jedem Rollback pruefen, ob ein aktuelles Backup existiert
+- nach jedem Rollback Funktion, Logs und Erreichbarkeit pruefen
+- wenn etwas unklar ist: stoppen, Zustand analysieren, dann gezielt eingreifen

docs/SECRETS_MAP.md

@@ -1,31 +1,39 @@
-# Secrets Map — Homelab
+# Secrets Map - Homelab
 
-Dieses Dokument listet alle sensiblen Daten (Passwörter, Tokens, Keys) und deren Speicherorte.
+Dieses Dokument listet sensible Daten, deren Ablageorte und die vorgesehene Einbindungsart.
 
 ## Grundregeln
+
 - Secrets liegen **niemals im Git-Repository**
-- Speicherort: `/mnt/user/appdata/secrets/`
+- Standardspeicherort: `/mnt/user/appdata/secrets/`
 - Berechtigungen: `chmod 600`
-- Nutzung in Docker über `_FILE` Variablen oder Komodo/Portainer Stack Environment Variables
+- Nutzung in Docker ueber `_FILE` Variablen oder Komodo Stack Environment Variables
 
 ---
 
-## Übersicht
+## Aktive Secrets
 
 | Service | Secret | Datei / Methode | Status |
 |---|---|---|---|
-| Vaultwarden | ADMIN_TOKEN | `vaultwarden_admin_token.txt` → `ADMIN_TOKEN_FILE` | ✅ |
-| PostgreSQL 17 | DB Password | `postgres_password.txt` → `POSTGRES_PASSWORD_FILE` | ✅ |
-| Mealie | DB Password | Stack ENV `${MEALIE_DB_PASSWORD}` (kein `_FILE`-Support) | ✅ |
-| mealie-postgres | DB Password | Stack ENV `${POSTGRES_PASSWORD}` | ✅ |
-| Gotify | User Passwort | `gotify_password.txt` → `GOTIFY_DEFAULTUSER_PASS_FILE` | ✅ |
-| Paperless-ngx | DB Password | Stack ENV `${PAPERLESS_DBPASS}` (kein `_FILE`-Support) | ✅ |
-| code-server | Passwort | `code_server_password.txt` → `PASSWORD_FILE` | ✅ |
-| Immich (server) | DB Password | Stack ENV `${IMMICH_DB_PASSWORD}` | ✅ |
-| immich-postgres | DB Password | `immich_db.txt` → `POSTGRES_PASSWORD_FILE` | ✅ |
-| mail-archiver | Auth Password | Stack ENV `${MAILARCHIVER_AUTH_PASSWORD}` | ✅ |
-| Borg UI / BorgBase | Admin-Login, `SECRET_KEY`, SSH-Keys, Repo-Passphrasen | app-intern persistiert unter `/mnt/user/appdata/borg-ui/data/` (DB + SSH-Key-Verzeichnis), nicht im Git | 🔄 |
-| ~~diun~~ | ~~Gotify Token~~ | ~~Stack ENV~~ | ❌ Container entfernt (2026-03-28) |
+| Vaultwarden | ADMIN_TOKEN | `vaultwarden_admin_token.txt` -> `ADMIN_TOKEN_FILE` | aktiv |
+| PostgreSQL 17 | DB Password | `postgres_password.txt` -> `POSTGRES_PASSWORD_FILE` | aktiv |
+| Mealie | DB Password | Stack ENV `${MEALIE_DB_PASSWORD}` | aktiv |
+| mealie-postgres | DB Password | Stack ENV `${POSTGRES_PASSWORD}` | aktiv |
+| Paperless-ngx | DB Password | Stack ENV `${PAPERLESS_DBPASS}` | aktiv |
+| code-server | Passwort | `code_server_password.txt` -> `PASSWORD_FILE` | aktiv |
+| Immich (server) | DB Password | Stack ENV `${IMMICH_DB_PASSWORD}` | aktiv |
+| immich-postgres | DB Password | `immich_db.txt` -> `POSTGRES_PASSWORD_FILE` | aktiv |
+| mail-archiver | Auth Password | Stack ENV `${MAILARCHIVER_AUTH_PASSWORD}` | aktiv |
+| Borg UI / Borg | Admin-Login, `SECRET_KEY`, SSH-Keys, Repo-Credentials | persistent unter `/mnt/user/appdata/borg-ui/data/` | aktiv |
+
+---
+
+## Historisch entfernte Secrets
+
+| Dienst | Frueherer Secret-Pfad / Mechanismus | Status |
+|---|---|---|
+| Gotify | `gotify_password.txt` / `GOTIFY_DEFAULTUSER_PASS_FILE` | Dienst nicht mehr aktiv |
+| diun | Stack ENV | Container entfernt |
 
 ---
 
@@ -33,20 +41,21 @@ Dieses Dokument listet alle sensiblen Daten (Passwörter, Tokens, Keys) und dere
 
 ```text
 /mnt/user/appdata/secrets/
-├── vaultwarden_admin_token.txt
-├── postgres_password.txt
-├── gotify_password.txt
-├── code_server_password.txt
-└── immich_db.txt
+|-- vaultwarden_admin_token.txt
+|-- postgres_password.txt
+|-- code_server_password.txt
+`-- immich_db.txt
 ```
 
-> **Hinweis:** Mealie, Paperless, mail-archiver und Immich-Server nutzen Stack Environment Variables statt Datei-Mounts, da `_FILE`-Support nicht vorhanden oder unzuverlässig ist.
+Hinweise:
 
-> **Hinweis zu Borg UI:** Die Anwendung erzeugt bzw. verwaltet ihr Session-Secret, den Admin-Login, SSH-Keys und Repo-Credentials in der persistenten `/data`-Struktur. Damit liegen keine Secrets im Git, aber die Sicherung von `/mnt/user/appdata/borg-ui/data/` ist für Restore und Disaster Recovery Pflicht.
+- Mealie, Paperless, mail-archiver und der Immich-Server nutzen Stack Environment Variables statt Datei-Mounts.
+- Borg UI verwaltet Session-Secret, Admin-Login, SSH-Keys und Repo-Credentials in seiner persistenten `/data`-Struktur. Diese Daten liegen nicht im Git, muessen aber gesichert werden.
 
 ---
 
 ## Regel
 
-Wenn `_FILE` nicht unterstützt wird → Stack Environment Variable in Komodo/Portainer verwenden.
+Wenn `_FILE` nicht unterstuetzt wird -> Stack Environment Variable in Komodo verwenden.
+
 Secrets niemals direkt in die Compose-Datei schreiben.