Konfigurationsreferenz¶

Vollständige Referenz zur Konfiguration von Bifolk über Umgebungsvariablen und Docker-Secrets.

Zielgruppe: Systemadministratoren, DevOps-Ingenieure

Konfigurationspriorität¶

Bifolk verwendet ein dreistufiges Konfigurationssystem:

Docker-Secrets (höchste Priorität) - Dateien in /run/secrets/
Umgebungsvariablen - In .env oder direkt gesetzt
Standardwerte (niedrigste Priorität) - Sichere Entwicklungsstandards

Der Konfigurationsfluss:

Container-Start → docker-entrypoint.sh → generate_config.py
  liest: Secrets → Umgebung → Standards
  erzeugt: bifolk.json → Django settings.py

Kern-Django-Einstellungen¶

Variable	Standard	Beschreibung
`DJANGO_DEBUG`	`True`	Debug-Modus. In Produktion auf `False` setzen
`DJANGO_SECRET_KEY`	(automatisch generiert)	Django-Kryptografie-Schlüssel
`DJANGO_ALLOWED_HOSTS`	`localhost,127.0.0.1`	Kommagetrennte Liste erlaubter Hostnamen
`DJANGO_CSRF_TRUSTED_ORIGINS`	(keine)	CSRF-vertrauenswürdige Origins mit Protokoll (z.B. `https://example.com`)
`SITE_DOMAIN`	(erster Eintrag in `ALLOWED_HOSTS`)	Öffentlicher Hostname des Deployments (z.B. `bee.example.org`). Wird in Einladungs-E-Mails, allauth-E-Mails und QR-Codes verwendet. Muss korrekt gesetzt sein, damit Links in E-Mails auf die richtige Adresse zeigen.
`TIME_ZONE`	`Europe/Berlin`	Zeitzone für die Anwendung

Datenbankeinstellungen¶

SQLite (Standard)¶

Wenn kein DB_HOST oder DB_NAME gesetzt ist, verwendet Bifolk SQLite:

Variable	Standard	Beschreibung
`DB_ENGINE`	(automatisch erkannt)	Explizit auf `django.db.backends.sqlite3` setzen
`DB_PATH`	`/bifolk/db/db.sqlite3`	Pfad zur SQLite-Datenbankdatei

PostgreSQL¶

Variable	Standard	Beschreibung
`DB_ENGINE`	(automatisch erkannt)	Auf `django.db.backends.postgresql` setzen
`DB_NAME`	`bifolk`	Datenbankname
`DB_USER`	`bifolk`	Datenbankbenutzer
`DB_PASSWORD`	(keine)	Datenbankpasswort (Docker-Secrets verwenden)
`DB_HOST`	`bifolk-db`	Datenbank-Host
`DB_PORT`	`5432`	Datenbank-Port

E-Mail-Einstellungen¶

Variable	Standard	Beschreibung
`EMAIL_HOST`	`smtp.example.com`	SMTP-Server-Hostname
`EMAIL_PORT`	`587`	SMTP-Port (587 für STARTTLS, 465 für implizites SSL)
`EMAIL_USE_TLS`	`True`	STARTTLS-Verschlüsselung verwenden (Port 587)
`EMAIL_USE_SSL`	`False`	Implizite SSL-Verschlüsselung verwenden (Port 465)
`EMAIL_USER`	`noreply@example.com`	SMTP-Benutzername
`EMAIL_PASSWORD`	(keine)	SMTP-Passwort (Docker-Secrets verwenden)
`DEFAULT_FROM_EMAIL`	`noreply@example.com`	Standard-"Von"-Adresse
`SERVER_EMAIL`	`root@localhost`	Server-E-Mail für Fehlerbenachrichtigungen

Warning

EMAIL_USE_TLS und EMAIL_USE_SSL schließen sich gegenseitig aus. Genau eine Option muss auf True gesetzt sein:

Port 587 (STARTTLS): EMAIL_USE_TLS=True, EMAIL_USE_SSL=False
Port 465 (implizites SSL): EMAIL_USE_TLS=False, EMAIL_USE_SSL=True

Note

Wenn DJANGO_DEBUG=True, werden E-Mails unabhängig von den SMTP-Einstellungen in der Konsole ausgegeben.

Authentifizierungseinstellungen¶

Variable	Standard	Beschreibung
`ALLOW_SELF_REGISTRATION`	`True`	Erlaubt Benutzern, sich selbst zu registrieren
`REQUIRE_EMAIL_VERIFICATION`	`True`	E-Mail-Verifizierung nach Registrierung erforderlich
`SESSION_TOKEN_LIFETIME_HOURS`	`168`	Sitzungslebensdauer in Stunden (Standard: 7 Tage)

MFA-Einstellungen¶

Variable	Standard	Beschreibung
`MFA_TOTP_ISSUER`	`Bifolk`	Name, der in Authenticator-Apps angezeigt wird
`MFA_REQUIRED`	`none`	MFA-Durchsetzung: `none`, `staff` oder `all`
`MFA_GRACE_PERIOD_DAYS`	`7`	Tage zum Einrichten von MFA vor Durchsetzung

OIDC / Single-Sign-On-Einstellungen¶

OIDC wird nur aktiviert, wenn OIDC_CLIENT_ID konfiguriert ist.

Variable	Standard	Beschreibung
`OIDC_PROVIDER_ID`	`authentik`	Provider-ID (wird in URLs verwendet)
`OIDC_PROVIDER_NAME`	`Single Sign-On`	Anzeigename auf der Login-Seite
`OIDC_CLIENT_ID`	(keine)	OAuth2-Client-ID
`OIDC_CLIENT_SECRET`	(keine)	OAuth2-Client-Secret (Docker-Secrets verwenden)
`OIDC_SERVER_URL`	(keine)	OIDC-Discovery-Basis-URL
`DISABLE_STANDARD_LOGIN`	`False`	Benutzername/Passwort-Login-Formular ausblenden

PWA-Einstellungen¶

Variable	Standard	Beschreibung
`PWA_ENABLED`	`True`	Progressive-Web-App-Funktionalität aktivieren

Variable	Standard	Beschreibung
`COOKIE_CONSENT_VERSION`	`1.0`	Erhöhen, um erneute Zustimmung zu erzwingen
`COOKIE_CONSENT_ANALYTICS_ENABLED`	`False`	Analyse-Cookie-Optionen anzeigen

Logging-Einstellungen¶

Variable	Standard	Beschreibung
`LOG_LEVEL`	`INFO`	Log-Level: DEBUG, INFO, WARNING, ERROR, CRITICAL
`LOG_RETENTION_DAYS`	`14`	Tage zur Aufbewahrung rotierter Log-Dateien (tägliche Rotation um Mitternacht)
`LOG_TO_CONSOLE`	`True`	Logs in Docker-Logs ausgeben
`LOG_TO_FILE`	`True`	Logs nach `/bifolk/logs/` schreiben

Proxy-Einstellungen¶

Variable	Standard	Beschreibung
`TRUSTED_PROXIES`	(keine)	Kommagetrennte Liste von Proxy-IP-Adressen, denen erlaubt ist, `X-Forwarded-For`- / `X-Real-IP`-Header zu setzen
`TRUST_X_FORWARDED_PROTO`	`False`	Auf `True` setzen, wenn Bifolk hinter einem HTTPS-terminierenden Reverse-Proxy betrieben wird. Weist Django an, den `X-Forwarded-Proto`-Header zu lesen, damit Einladungslinks und alle anderen generierten URLs `https://` statt `http://` verwenden. Nur aktivieren, wenn der Proxy unter eigener Kontrolle steht.

Important

TRUSTED_PROXIES sollte nur gesetzt werden, wenn Bifolk hinter einem Reverse-Proxy betrieben wird (z. B. Traefik, Nginx). Für direkte Deployments leer lassen.

Wenn leer (Standard), werden Proxy-Header ignoriert und die direkte TCP-Verbindungsadresse (REMOTE_ADDR) wird immer als Client-IP verwendet. Dies ist die sichere Voreinstellung.

Wenn gesetzt, werden Proxy-Header nur dann vertraut, wenn die Verbindung von einer der aufgeführten IP-Adressen stammt — dies verhindert, dass Clients ihre IP-Adresse in Audit-Logs fälschen.

Beispiel (einzelner Traefik-Container in einem Docker-Netzwerk):

TRUSTED_PROXIES=172.17.0.1

Mehrere Proxys:

TRUSTED_PROXIES=172.17.0.1,10.0.0.1

Fehler-Tracking-Einstellungen¶

Bifolk kann nicht behandelte Ausnahmen an einen Sentry-kompatiblen Fehler-Tracker wie eine selbst gehostete GlitchTip-Instanz melden. Das Fehler-Tracking ist standardmäßig deaktiviert und wird nur aktiviert, wenn SENTRY_DSN gesetzt ist.

Variable	Standard	Beschreibung
`SENTRY_DSN`	(keine)	DSN aus Ihren Sentry/GlitchTip-Projekteinstellungen. Nicht setzen, um das Fehler-Tracking zu deaktivieren.
`SENTRY_TRACES_SAMPLE_RATE`	`0.0`	Anteil der Anfragen, die als Performance-Traces aufgezeichnet werden (0.0 = deaktiviert, 1.0 = alle Anfragen).

Note

Es werden keine personenbezogenen Daten an den Fehler-Tracker übermittelt. IP-Adressen, E-Mail-Adressen und Session-Cookies der Benutzer sind ausgeschlossen (send_default_pii=False).

Tip

Für Produktionsumgebungen empfiehlt sich die Verwendung der Docker-Secret-Variante SENTRY_DSN_FILE anstatt des DSN direkt in der Umgebungsdatei. Siehe Docker-Secrets für Details.

Application-Server-Einstellungen¶

Variable	Standard	Beschreibung
`GUNICORN_WORKERS`	`3`	Anzahl der Gunicorn-Worker-Prozesse. Faustregel: 2–4 × Anzahl der CPU-Kerne.

Dokumentationseinstellungen¶

Variable	Standard	Beschreibung
`DOCS_URL`	(keine)	Wenn gesetzt, erscheint ein "Docs"-Link in der Navigationsleiste

Docker-Compose-Einstellungen¶

Variable	Standard	Beschreibung
`APP_PORT`	`8000`	Externer Port für die Anwendung
`APP_DOCS_PORT`	`8001`	Externer Port für den Dokumentationsserver
`TIME_ZONE`	`Europe/Berlin`	Container-Zeitzone

Docker-Secrets¶

Für sensible Werte verwenden Sie Docker-Secrets anstelle von Umgebungsvariablen:

Secret-Datei	Umgebungsvariable	Zweck
`secrets/secret_key.txt`	`DJANGO_SECRET_KEY`	Django SECRET_KEY
`secrets/db_password.txt`	`DB_PASSWORD`	Datenbankpasswort
`secrets/email_password.txt`	`EMAIL_PASSWORD`	SMTP-Passwort
`secrets/oidc_client_secret.txt`	`OIDC_CLIENT_SECRET`	OIDC-Client-Secret
`secrets/sentry_dsn.txt`	`SENTRY_DSN`	Sentry/GlitchTip DSN

Siehe Docker-Secrets für Details.