234 lines
6.3 KiB
Markdown
234 lines
6.3 KiB
Markdown
# 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";
|
|
};
|
|
};
|
|
```
|
|
|
|
Secrets werden nicht als manuell gepflegte Datei unter `/var/lib/frappe` verwaltet, sondern wie bei den anderen Diensten über agenix bereitgestellt. Das Frappe-Modul referenziert dafür einen age-Secret-Pfad, z.B.:
|
|
|
|
```nix
|
|
frappeEnvFile = config.age.secrets.frappe-env.path;
|
|
```
|
|
|
|
Die zugehörige Secret-Datei enthält die für Init und Site-Erzeugung benötigten Variablen, insbesondere:
|
|
|
|
```text
|
|
FRAPPE_DB_ADMIN_PASSWORD=<database-admin-secret>
|
|
FRAPPE_ADMIN_PASSWORD=<site-administrator-secret>
|
|
```
|
|
|
|
Der Secret-Eintrag wird in den bestehenden agenix-Strukturen ergänzt:
|
|
|
|
```text
|
|
secrets/frappe-env.age
|
|
secrets.nix
|
|
hosts/AZ-CLD-1/secrets.nix
|
|
```
|
|
|
|
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.
|
|
- Secrets werden ausschließlich über `config.age.secrets.*.path` eingebunden.
|
|
- Eine fehlende agenix-Secret-Definition oder fehlende Variablen im Secret führen zu einem klaren Fehler.
|
|
- Es wird keine dauerhafte, manuell gepflegte Secret-/Env-Datei unter `/var/lib/frappe` erzeugt.
|
|
- 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`.
|
|
- `containers/frappe.nix` verwendet agenix-Secrets über `config.age.secrets.*.path` statt eine manuelle `/var/lib/frappe/*.env`-Datei zu erwarten.
|
|
- `services/default.nix` importiert `mariadb.nix` und `redis.nix`.
|
|
- `containers/default.nix` importiert `frappe.nix` statt `frappe-lms.nix`.
|
|
- `secrets/frappe-env.age`, `secrets.nix` und `hosts/AZ-CLD-1/secrets.nix` sind konsistent ergänzt.
|