Konfiguration

Konfiguration

.env.example ist die Referenz für lokale Entwicklung. .env.e2e.example, .env.test.example und .env.prod.example beschreiben die jeweiligen Umgebungen. Echte .env-Dateien werden nicht committed und müssen auf Deploy-Hosts Modus 600 besitzen; Symlinks und gruppen-/weltlesbare Dateien lehnt der sichere Loader ab.

Datenbank

Variable	Zweck
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD	PostgreSQL-Initialisierung
DATABASE_URL	privilegierte Admin-/Alembic-Verbindung
APP_DB_PASSWORD, APP_DATABASE_URL	eingeschränkte Hauptanwendung
ABGABEBOX_DB_PASSWORD, ABGABEBOX_DATABASE_URL	eingeschränkte Abgabebox-Rolle

Passwörter und URLs müssen konsistent sein. Die Laufzeitanwendung soll nicht mit der privilegierten Alembic-Verbindung arbeiten.

Domains und Routing

Variable	Zweck
TRAEFIK_DOMAIN	Hauptanwendung
TRAEFIK_ADMIN_DOMAIN, TRAEFIK_ADMIN_PORT	privater Platform-Admin-Zugang
TRAEFIK_ABGABEBOX_DOMAIN	öffentliche Abgabebox
TRAEFIK_DOCS_DOMAIN	weiterhin betriebene MkDocs-Seite
ACME_EMAIL	Let's-Encrypt-Kontakt
CF_DNS_API_TOKEN	auf die DNS-Zone beschränktes Cloudflare-Token
TRAEFIK_WEB_BIND, TRAEFIK_WEBSECURE_BIND	Host-Bind-Adresse für Port 80/443, Default 0.0.0.0 (öffentlich)
TRAEFIK_CERTRESOLVER	Certresolver für alle Nicht-Admin-Router, Default letsencrypt (HTTP-01)

Vor dem ersten Start einer externen Domain muss DNS bereits auf den Host zeigen.

Test-Host komplett privat betreiben (wie der Admin-Zugang)

Wenn ein Host nicht öffentlich im Internet stehen soll, sondern wie der Platform-Admin-Zugang ausschliesslich über einen privaten OpenZiti-Tunnel erreichbar sein soll:

TRAEFIK_WEB_BIND=127.0.0.1
TRAEFIK_WEBSECURE_BIND=127.0.0.1
TRAEFIK_CERTRESOLVER=letsencryptdns

Damit binden Port 80 und 443 nur noch an 127.0.0.1 (wie bereits TRAEFIK_ADMIN_PORT) und alle Router beziehen ihre Zertifikate über die Cloudflare-DNS-01-Challenge statt über die öffentlich nicht mehr erreichbare HTTP-01-Challenge. CF_DNS_API_TOKEN muss dafür gesetzt sein (ohnehin für den Admin-Zugang erforderlich). Die Traefik-/Compose-Seite ist damit erledigt - den eigentlichen OpenZiti-Service, der 127.0.0.1:443 auf dem Host für berechtigte Clients freigibt, muss man zusätzlich genauso einrichten, wie es für den Admin-Port (127.0.0.1:8443) bereits gemacht wurde; das ist Teil der OpenZiti-Netzwerkkonfiguration ausserhalb dieses Repos. Ohne diesen Tunnel ist der Host danach für alle - auch berechtigte Tester - unerreichbar.

Für Prod bleiben beide Bind-Variablen und TRAEFIK_CERTRESOLVER ungesetzt (Default: öffentlich, HTTP-01) - diese Einstellung ist unabhängig pro Host über die jeweilige .env.

Frontend und Version

Variable	Zweck
NEXT_PUBLIC_API_URL	öffentliche API-Basis/Runtime-Konfiguration
INTERNAL_API_URL	serverseitige Frontend-Zugriffe
HOCX_VERSION	sichtbare Version und Release-Pinning

Browser-Aufrufe sind same-origin. Auf Test/Prod wird HOCX_VERSION auf den Candidate- bzw. finalen Release-Tag gesetzt.

Authentifizierung

Variable	Zweck
AUTH_SECRET	Signatur der Kundensitzung
ADMIN_AUTH_SECRET	getrennte Platform-Admin-Sitzung
INITIAL_ADMIN_EMAIL, INITIAL_ADMIN_PASSWORD	einmaliger erster Platform-Admin

Die beiden Secrets müssen verschieden und mindestens 32 Zeichen lang sein. Bootstrap- Zugangsdaten wirken nur, solange noch kein Platform-Admin existiert, und werden nach dem ersten Login geändert.

Storage und Uploads

Variable	Zweck
HOCX_STORAGE_PATH	Host-/Volume-Pfad für persistente Dateien
FRIENDLY_CAPTCHA_SITEKEY, FRIENDLY_CAPTCHA_API_KEY	öffentliche Upload-Prüfung
ABGABEBOX_CAPTCHA_SESSION_SECRET	CAPTCHA-Sitzung
ABGABEBOX_ENVIRONMENT	Fail-open nur in Dev/Test, fail-closed in Produktion

ABGABEBOX_ENVIRONMENT darf in Produktion nicht auf einen Dev-/Testwert gesetzt sein. Leere CAPTCHA-Schlüssel sind nur in isolierten Entwicklungs- und E2E-Umgebungen zulässig.

Backend-interne Einstellungen

Zusätzliche Settings in backend/app/core/config.py steuern unter anderem Storage- Unterpfade, Redis, ClamAV, Session-Laufzeiten, Domain-Healthchecks, Rescan-Intervalle, Upload-Quotas sowie Export-, Audit- und Error-Log-Retention. Bei Einführung einer neuen Variable sind immer anzupassen:

1. typisierte Settings-Klasse mit sicherem Default;
2. relevante Compose-Dateien;
3. Beispiel-Env der betroffenen Umgebungen;
4. sicherer Env-Loader/Allowlist, falls Deploy-Skripte sie lesen;
5. Tests und diese Seite.

Secrets

• keine Secrets in Git, Wiki, Issues, Screenshots oder Logs;
• Cloudflare-Token minimal auf Zone/DNS beschränken;
• GitHub- und GHCR-Tokens getrennt halten;
• Deploy-Tokens liegen geschützt unter .tools/, nicht in .env;
• kompromittierte Werte sofort rotieren, nicht nur aus dem letzten Commit löschen.

Umgebungsvergleich

Eigenschaft	Dev	E2E	Test	Prod
Code	lokaler Build	isolierter lokaler Build	GHCR Candidate	GHCR Release
Daten	persistent lokal	nach Lauf gelöscht	separate Testdaten	Echtdaten
CAPTCHA	Dev/Test	Dev/Test	gemäss Testkonfiguration	fail-closed
Version	dev	e2e	test-*	vX.Y.Z
Secrets	lokale Beispiele	feste Testwerte	generiert/geschützt	generiert/geschützt

Die vollständige Produktionskonfiguration wird durch deploy.sh validiert. Fehlende Pflichtwerte oder unsichere Dateirechte müssen fail-closed zum Abbruch führen.