AZ-NIX-SERVERS/docs/superpowers/specs/2026-06-05-frappe-bench-infrastruktur-design.md

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:

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:

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:

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:

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:

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:

sites = {
  "learn.az-gruppe.com" = {
    apps = [ "lms" ];
    adminPasswordEnv = "FRAPPE_ADMIN_PASSWORD";
  };
};

Weitere Sites können später ergänzt werden, ohne die Grundstruktur umzubauen:

sites."portal.az-gruppe.com" = {
  apps = [ "lms" "custom_app" ];
};

Die globalen Bench-Settings werden einmalig gesetzt:

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:

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:

frappe {init|migrate|backup|status}

Nicht mehr:

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:

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:

nix flake check
nixos-rebuild build --flake .#AZ-CLD-1

Nicht erlaubt im Rahmen dieser Änderung:

nixos-rebuild switch

Ebenfalls nicht ausführen:

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.