# 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`.