Konfiguration

Konfiguration (Environment-Referenz)

Die API wird vollständig über Umgebungsvariablen konfiguriert — per Shell, .env-Datei (Docker --env-file) oder Compose. Stand: v1.2.0.

Eine kommentierte Vorlage mit allen Variablen pflegt die Hauptanwendung: .env.example (siehe auch App-Wiki → Konfiguration).

---

Kernvariablen

Variable	Default	Zweck
SP5_DB_PATH	(setzen!)	Verzeichnis mit den Schichtplaner5-.DBF-Dateien. Wird beim Start auch ins Environment publiziert, damit die Bibliothek (sp5lib, z. B. Auto-Migration) denselben Pfad sieht.
SP5_BACKEND_DIR	Elternverzeichnis des Pakets	Ressourcen-Root der Host-Anwendung: <dir>/data, <dir>/api/data, <dir>/api/uploads, Alembic-Konfiguration. Gemeinsamer Vertrag mit sp5lib — bei installierten Deployments setzen.
SP5_FRONTEND_DIST	<SP5_BACKEND_DIR>/../frontend/dist	Gebaute SPA, die unter / ausgeliefert wird; fehlt das Verzeichnis → reiner API-Modus.
SP5_JWT_SECRET / SECRET_KEY	Zufallswert pro Prozess	JWT-Signatur-Secret. In Produktion setzen — sonst verfallen alle Sessions beim Neustart (Warnung im Log). SP5_JWT_SECRET hat Vorrang.
SP5_DEV_MODE	aus	Dev-Bypass-Token (__dev_mode__ wirkt als Admin) — niemals in Produktion.
ALLOWED_ORIGINS	localhost:5173/8000	CORS-Origins (kommagetrennt).
DB_BACKEND / DATABASE_URL	dbf	Umschalten auf den PostgreSQL-Mirror (über sp5lib); siehe Lib-Wiki.

Rate-Limits & Login-Schutz

Variable	Default	Zweck
RATE_LIMIT_API	100/minute	Globales Rate-Limit pro Benutzer bzw. IP
RATE_LIMIT_LOGIN	5/minute	Limit für Credential-Endpoints (Login, Passwort-Routen)
BRUTE_FORCE_MAX_ATTEMPTS	5	Fehlversuche bis zur Sperre (pro Benutzername)
BRUTE_FORCE_LOCKOUT_MINUTES	15	Dauer der Sperre

Sessions & Tokens

Variable	Default	Zweck
TOKEN_EXPIRE_HOURS	8	JWT-/Session-Laufzeit in Stunden
MAX_SESSIONS_PER_USER	10	Maximale parallele Sessions; die älteste wird verdrängt
SESSION_CLEANUP_INTERVAL_MINUTES	5	Intervall des Aufräum-Tasks für abgelaufene Sessions/Lockouts

Passwort-Policy

Variable	Default	Zweck
SP5_PW_MIN_LENGTH	8	Mindestlänge neuer Passwörter
SP5_PW_REQUIRE_UPPER	true	Großbuchstabe erforderlich
SP5_PW_REQUIRE_DIGIT	true	Ziffer erforderlich

Logging & Audit

Variable	Default	Zweck
LOG_FILE	/tmp/sp5-api.log	Logdatei (rotierend, 10 MB × 3); bei unbeschreibbarem Pfad Fallback auf den Default
LOG_LEVEL / SP5_LOG_LEVEL	INFO	Log-Level (SP5_LOG_LEVEL hat Vorrang)
SP5_LOG_FORMAT	json	json (strukturiert) oder Text
SP5_AUDIT_LOG	/tmp/sp5-audit.json	Audit-Log sicherheitsrelevanter Aktionen (JSON-Lines)

Security-Header

Variable	Default	Zweck
SP5_HSTS	aus	Strict-Transport-Security-Header aktivieren (nur hinter TLS sinnvoll)
CSP_REPORT_ONLY	aus	Content-Security-Policy nur melden statt erzwingen

E-Mail (SMTP)

Der E-Mail-Versand (Benachrichtigungen, Passwort-Reset, Scheduled Reports) läuft über den E-Mail-Service der Bibliothek; die SMTP-Variablen (SMTP_HOST, SMTP_PORT, Zugangsdaten, Absender) sind in der .env.example der Hauptanwendung dokumentiert. Status und Test: GET /api/email/config, POST /api/email/test (Admin).

---

Hinweise

• Booleans: Schalter wie SP5_DEV_MODE, SP5_HSTS, CSP_REPORT_ONLY akzeptieren 1/true/yes.
• Robuste Defaults: Ungültige Zahlenwerte (Tippfehler) führen nicht zum Startabbruch, sondern zum jeweiligen Default.
• Docker: Im offiziellen Image sind SP5_DB_PATH=/app/data und SP5_BACKEND_DIR=/app/backend vorbelegt — siehe Installation-und-Betrieb.

Siehe auch

• Installation-und-Betrieb — wo die Variablen gesetzt werden
• Authentifizierung-und-Rechte — Wirkung der Auth-Variablen im Detail