docs: design frappe bench infrastructure

2026-06-05 09:25:21 +02:00
parent 712feb1fa3
commit 1c3ecce5ca
1 changed files with 208 additions and 0 deletions
@@ -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/<domain>/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`.