diff --git a/docs/superpowers/specs/2026-06-05-frappe-bench-infrastruktur-design.md b/docs/superpowers/specs/2026-06-05-frappe-bench-infrastruktur-design.md new file mode 100644 index 0000000..8cd612c --- /dev/null +++ b/docs/superpowers/specs/2026-06-05-frappe-bench-infrastruktur-design.md @@ -0,0 +1,208 @@ +# Frappe Bench Infrastruktur-Design + +Datum: 2026-06-05 +Host: `AZ-CLD-1` +Status: abgestimmtes Design, noch nicht umgesetzt + +## Ziel + +Das bestehende Frappe-LMS-Setup soll strukturell in eine produktionsnahe, erweiterbare Frappe-Bench-Architektur überführt werden. + +Kernentscheidungen: + +- Frappe läuft produktionsnah getrennt nach Prozessen: Backend, Frontend/Nginx, Websocket, Worker und Scheduler. +- Die Frappe-Laufzeit wird als gemeinsame Bench für mehrere Sites verstanden. +- Redis läuft als Host-Infrastruktur und nicht mehr als LMS-spezifischer Container. +- MariaDB läuft als Host-Infrastruktur und orientiert sich strukturell an `hosts/AZ-CLD-1/services/postgres.nix`. +- Die Docker-Compose-Vorlage dient als Referenz für MariaDB-/Redis-/Bench-Erwartungen, nicht als 1:1 Container-Topologie. +- Es wird kein `nixos-rebuild switch` und kein `git push` im Rahmen dieser Änderung ausgeführt. Ein Build-Test ist erlaubt. + +## Zielstruktur + +Neue bzw. geänderte Dateien: + +```text +hosts/AZ-CLD-1/services/mariadb.nix +hosts/AZ-CLD-1/services/redis.nix +hosts/AZ-CLD-1/services/containers/frappe.nix +``` + +Die bestehende Datei: + +```text +hosts/AZ-CLD-1/services/containers/frappe-lms.nix +``` + +wird inhaltlich in `frappe.nix` überführt, weil sie künftig die gemeinsame Frappe-Bench repräsentiert und nicht nur die LMS-Site. + +## MariaDB + +MariaDB wird zentral als Host-Service definiert. Das Frappe-Modul darf nicht mehr selbst `services.mysql` aktivieren. + +`mariadb.nix` übernimmt analog zu `postgres.nix`: + +- Aktivierung des Host-Datenbankdienstes +- zentrale Datenbank-Settings +- Firewall-Freigaben für erlaubte Netze +- Frappe-kompatible Admin-/Init-Logik +- perspektivisch zentrale Backups + +Die MariaDB-Settings aus der Compose-Vorlage werden übernommen: + +```text +character-set-server = utf8mb4 +collation-server = utf8mb4_unicode_ci +skip-character-set-client-handshake = true +skip-innodb-read-only-compressed = true +``` + +Frappe-Container erreichen MariaDB über die Podman-Host-IP: + +```text +10.89.0.1:3306 +``` + +Die Firewall erlaubt Zugriff nur aus dem Podman-Netz, insbesondere `10.89.0.0/24`. + +## Redis + +Redis wird zentral als Host-Service definiert. Frappe bringt keine eigenen Redis-Container mehr mit. + +Frappe nutzt einen gemeinsamen Host-Redis mit getrennten logical DBs: + +```text +redis_cache redis://10.89.0.1:6379/1 +redis_queue redis://10.89.0.1:6379/2 +redis_socketio redis://10.89.0.1:6379/2 +``` + +Damit bleibt das Setup nah an der Compose-Vorlage, die ebenfalls nur einen Redis-Service definiert, vermeidet aber Kollisionen mit anderen Host-Verbrauchern. + +Firewall-Regel: + +- Zugriff lokal erlauben +- Zugriff aus `10.89.0.0/24` erlauben +- keine allgemeine externe Freigabe + +## Frappe Bench + +`containers/frappe.nix` beschreibt eine gemeinsame Frappe-Bench mit Multisite-Fähigkeit. + +Die erste Site bleibt: + +```nix +sites = { + "learn.az-gruppe.com" = { + apps = [ "lms" ]; + adminPasswordEnv = "FRAPPE_ADMIN_PASSWORD"; + }; +}; +``` + +Weitere Sites können später ergänzt werden, ohne die Grundstruktur umzubauen: + +```nix +sites."portal.az-gruppe.com" = { + apps = [ "lms" "custom_app" ]; +}; +``` + +Die globalen Bench-Settings werden einmalig gesetzt: + +```text +db_host 10.89.0.1 +db_port 3306 +redis_cache redis://10.89.0.1:6379/1 +redis_queue redis://10.89.0.1:6379/2 +redis_socketio redis://10.89.0.1:6379/2 +socketio_port 9000 +``` + +## Container-Prozesse + +Die produktionsnahe Trennung bleibt erhalten: + +```text +frappe-backend +frappe-frontend +frappe-websocket +frappe-queue-short +frappe-queue-long +frappe-scheduler +``` + +Die Container teilen sich das gemeinsame Sites-Verzeichnis unter `/var/lib/frappe/sites` oder einer äquivalenten Bench-Datenstruktur. + +Die Frontend-/Nginx-Instanz bleibt über Traefik erreichbar. Für `learn.az-gruppe.com` bleibt die bestehende Traefik-Domain erhalten. + +## Initialisierung + +Die Initialisierung bleibt idempotent: + +- Verzeichnisse werden vorbereitet. +- Fehlende Env-Datei oder fehlende Secrets führen zu einem klaren Fehler. +- Gemeinsame Bench-Konfiguration wird gesetzt. +- Existiert `sites//site_config.json`, wird die Site-Erzeugung übersprungen. +- Existiert die Site nicht, wird sie mit `bench new-site` angelegt. +- Apps werden gemäß Site-Konfiguration installiert. + +Für die erste Site wird `lms` installiert. + +## CLI-Helfer + +Der bisherige Helfer wird allgemeiner benannt: + +```text +frappe {init|migrate|backup|status} +``` + +Nicht mehr: + +```text +frappe-lms ... +``` + +`status` prüft künftig: + +- `mysql.service` +- `redis.service` +- Frappe-Konfigurations-/Init-Services +- alle Frappe-Podman-Container + +## Backups + +Kurzfristig bleibt der Frappe-Backup-Mechanismus: + +```bash +bench --site all backup --with-files +``` + +MariaDB-Backups werden zentral im MariaDB-Modul ergänzt, soweit die NixOS-Optionen bzw. vorhandenen Backup-Patterns dies sauber unterstützen. + +## Validierung + +Erlaubt: + +```bash +nix flake check +nixos-rebuild build --flake .#AZ-CLD-1 +``` + +Nicht erlaubt im Rahmen dieser Änderung: + +```bash +nixos-rebuild switch +``` + +Ebenfalls nicht ausführen: + +```bash +git push +``` + +Zusätzliche statische Prüfungen: + +- `containers/frappe.nix` enthält keine Redis-Container mehr. +- `containers/frappe.nix` definiert nicht mehr `services.mysql`. +- `services/default.nix` importiert `mariadb.nix` und `redis.nix`. +- `containers/default.nix` importiert `frappe.nix` statt `frappe-lms.nix`.