Environment-Variablen

Nach einer Änderung: Konfiguration anwenden. Laufzeitwerte werden durch Neuerstellen der betroffenen Container übernommen; VITE_*-Werte benötigen einen Frontend-Build. Ein bloßer Neustart genügt dafür nicht.

Environment-Variablen steuern den Betrieb von StatO. Der Environment Generator erzeugt sichere Standardwerte als deploy.yaml oder stato.env. Für besondere Infrastruktur, externe Datenbanken oder Entwicklungsumgebungen dient diese Seite als Referenz.

:::caution Secrets JWT_SECRET, Datenbank- und SMTP-Passwörter sowie S3-Schlüssel sind Secrets. Sie gehören in einen Secret Store, eine geschützte lokale Datei oder die sichere Variablenverwaltung der Hosting-Plattform – nie in Git. :::

Laufzeit, HTTP und Reverse Proxy

Variable	Standard / Format	Zweck
`NODE_ENV`	`production`	Node-Laufzeitmodus. In Produktion immer `production`.
`APP_ENV`	`production`, `staging`, `development`	App-spezifischer Betriebsmodus.
`STRICT_SECURITY_MODE`	`true`, `false`	Erzwingt produktionsnahe Sicherheitsprüfungen.
`TZ`	z. B. `Europe/Berlin`	Zeitzone für Container und Logs.
`PORT`	meist `3000`	Interner Backend-Port; bei Compose normalerweise nicht extern freigeben.
`API_PREFIX`	meist `api`	Prefix der API-Routen.
`APP_ORIGIN`	vollständige URL	Öffentliche Browser-Adresse; Grundlage für Einladungen, Reset- und 2FA-Links.
`CORS_ORIGINS`	eine oder mehrere Origins	Erlaubte Browser-Ursprünge, durch Komma getrennt.
`TRUST_PROXY`	`true`, `false`	Hinter Reverse Proxy normalerweise `true`, damit Client-IP und Rate Limits stimmen.
`SWAGGER_ENABLED`	`true`, `false`	Backend-API-Dokumentation; in Produktion normalerweise `false`.
`HTTP_BIND_ADDRESS`	z. B. `0.0.0.0`	Bind-Adresse des On-Premises-Frontends im Release-Bundle.
`HTTP_PORT`	z. B. `80`, `8088`	Veröffentlichter HTTP-Port im Release-Bundle.
`STATO_TLS_MODE`	`off`, `internal`	Schaltet internes Caddy-TLS im Release-Bundle.
`STATO_PUBLIC_HOST`	DNS-Name	Öffentlicher Name für internes Caddy-TLS.
`HTTPS_BIND_ADDRESS`	z. B. `0.0.0.0`	Bind-Adresse von Caddy.
`HTTPS_PORT`	meist `443`	HTTPS-Port von Caddy.

Datenbank und Migrationen

Variable	Standard / Format	Zweck
`DB_TYPE`	`postgres`	Datenbanktreiber des Backends.
`DB_HOST`	Hostname	Datenbankhost, im Stack meist `postgres`.
`DB_PORT`	meist `5432`	Datenbankport, wichtig bei externer Datenbank.
`DB_USERNAME`	Benutzername	Datenbankbenutzer des Backends.
`DB_PASSWORD`	Secret	Passwort der Backend-Datenbankverbindung.
`DB_DATABASE`	Datenbankname	Name der genutzten Datenbank.
`POSTGRES_DB`	`stato_prod`	Initialer Datenbankname des mitgelieferten Postgres-Containers.
`POSTGRES_USER`	`stato_user`	Initialer Benutzer des Postgres-Containers.
`POSTGRES_PASSWORD`	Secret	Passwort des Postgres-Containers.
`DB_SYNCHRONIZE`	`false`	Automatische TypeORM-Schema-Synchronisierung; in Produktion immer `false`.
`DB_MIGRATIONS_RUN`	`true`	Führt kontrollierte Migrationen beim Backend-Start aus.
`DB_BOOTSTRAP_ON_EMPTY`	`true`, `false`	Initialisiert eine leere Datenbank im vorgesehenen Erststartpfad.
`DB_LOGGING`	`false`	SQL-Logging; nur kurzzeitig zur Diagnose aktivieren.
`DB_REQUIRE_SSL`	`true`, `false`	Erzwingt TLS für externe Datenbanken.
`DB_SSL`	`true`, `false`, `require`	Aktiviert TLS für die DB-Verbindung.
`DB_SSL_REJECT_UNAUTHORIZED`	`true`, `false`	Prüft DB-Zertifikate; für vertrauenswürdige Produktionszertifikate `true`.

Anmeldung, Sitzungen und Sicherheit

Variable	Standard / Format	Zweck
`JWT_SECRET`	mindestens 64 zufällige Zeichen	Signatur-Secret für Anmeldung und Sessions; stabil halten.
`JWT_ACCESS_EXPIRATION`	z. B. `15m`	Laufzeit des Access-Tokens.
`JWT_REFRESH_EXPIRATION`	z. B. `7d`	Laufzeit der Refresh-Session.
`AUTH_REFRESH_COOKIE_SAMESITE`	`lax`, `strict`, `none`	SameSite-Regel des Refresh-Cookies.
`AUTH_REFRESH_COOKIE_SECURE`	`true`, `false`	Secure-Flag des Cookies; bei HTTPS `true`.
`INVITE_TOKEN_EXPIRATION`	z. B. `24h`	Gültigkeit von Einladungslinks.
`RESET_TOKEN_EXPIRATION`	z. B. `1h`	Gültigkeit von Passwort-Reset-Links.
`PASSWORD_RESET_MODE`	`email`, `admin_temp_password`, `hybrid`	Passwort-Reset per E-Mail, Admin oder beides.
`USER_PROVISIONING_MODE`	`email`, `local`	Benutzer:innen per E-Mail einladen oder lokal mit temporärem Passwort anlegen.
`AUTH_2FA_ENABLED`	`true`, `false`	Aktiviert E-Mail-basierte Zwei-Faktor-Anmeldung; SMTP ist dann Pflicht.
`AUTH_2FA_CODE_TTL`	Sekunden, z. B. `600`	Gültigkeit eines 2FA-Codes.

Siehe auch Einladungen, lokale Zugänge und Passwort-Reset und Zwei-Faktor-Anmeldung per E-Mail.

Rate Limits und Listen

Variable	Standard / Format	Zweck
`RATE_LIMIT_TTL`	Sekunden, meist `60`	Zeitfenster des allgemeinen Rate Limits.
`RATE_LIMIT_MAX`	Ganzzahl, meist `100`	Maximale Requests pro Client im allgemeinen Fenster.
`AUTH_RATE_LIMIT_TTL`	Sekunden, meist `60`	Zeitfenster für Login und andere Auth-Endpunkte.
`AUTH_RATE_LIMIT_MAX`	Ganzzahl, meist `10`	Maximale Auth-Requests im Auth-Fenster.
`LOGIN_MAX_FAILED_ATTEMPTS`	meist `5`	Fehlversuche bis zur Sperre.
`LOGIN_LOCKOUT_MINUTES`	meist `10`	Dauer der temporären Kontosperre.
`DEFAULT_PAGE_SIZE`	z. B. `20`	Standardgröße paginierter API-Antworten.
`MAX_PAGE_SIZE`	z. B. `100`	Obergrenze für API-Listen pro Request.

Ersteinrichtung, Branding und Verhalten

Variable	Standard / Format	Zweck
`SUPERADMIN_EMAIL`	gültige E-Mail	Superadmin für den Erststart oder bewussten Reset.
`SUPERADMIN_PASSWORD`	starkes Secret	Initiales Superadmin-Passwort, falls nicht über Browser-Ersteinrichtung gesetzt.
`SUPERADMIN_EMAIL_FORCE`	`true`, `false`	Überschreibt bestehende Superadmin-E-Mail nur bei bewusstem Reset.
`SUPERADMIN_PASSWORD_FORCE`	`true`, `false`	Setzt ein bestehendes Superadmin-Passwort nur bei bewusstem Reset neu.
`INITIAL_SETUP_ENABLED`	`true`, `false`	Erlaubt bei leerer Datenbank einmalig die Passwortvergabe im Browser.
`PUBLIC_APP_NAME`	Freitext	Anzeigename der Anwendung.
`PUBLIC_ORG_NAME`	Freitext	Optionaler Organisationsname auf der Login-Seite.
`PUBLIC_LOGIN_SUBTITLE`	Freitext	Untertitel der Login-Seite.
`PUBLIC_LIVE_REFRESH_INTERVAL_MS`	Millisekunden, z. B. `30000`	Aktualisierungsintervall für Dashboard, Aktivitäten und Statistik; `0` deaktiviert es.
`STATS_OVERVIEW_CACHE_TTL_MS`	Millisekunden, z. B. `30000`	Cache-Dauer zusammengefasster Statistikabfragen; `0` deaktiviert sie.

SMTP und E-Mail

Variable	Standard / Format	Zweck
`SMTP_HOST`	Hostname	SMTP-Server für Einladungen, Passwort-Reset und 2FA.
`SMTP_PORT`	meist `587` oder `465`	SMTP-Port.
`SMTP_USER`	Benutzername oder E-Mail	SMTP-Anmeldung.
`SMTP_PASS`	Secret	SMTP-Passwort.
`SMTP_FROM`	gültige E-Mail	Absenderadresse der StatO-Systemmails.

Rechtstexte

Variable	Standard / Format	Zweck
`LEGAL_CONTENT_DIR`	Containerpfad	Ablageort für eingebundene Rechtstexte.
`LEGAL_CONTENT_DIR_HOST`	Hostpfad	Host-Verzeichnis, das schreibgeschützt als Rechtstexte eingebunden wird.

Feature-Flags und Seeds

Variable	Standard / Format	Zweck
`ENABLE_ORG_MOVE`	`true`, `false`	Aktiviert Organisationsverschiebungen im Backend.
`VITE_ENABLE_ORG_MOVE`	`true`, `false`	Frontend-Build-Flag für Organisationsverschiebungen.
`VITE_ENABLE_DEV_TOOLS`	`true`, `false`	Frontend-Build-Flag für Dev Tools; Produktion: `false`.
`SEED_ALLOW_PROD`	`true`, `false`	Erlaubt Seeds ausnahmsweise in produktionsnahen Umgebungen.
`SEED_ORGS`	Ganzzahl	Anzahl erzeugter Organisationen.
`SEED_STAFF_PER_ORG`	Ganzzahl	Anzahl erzeugter Mitarbeitender je Organisation.
`SEED_ACTIVITIES`	Ganzzahl	Anzahl erzeugter Aktivitäten.
`SEED_PROJECTS_PER_ORG`	Ganzzahl	Anzahl erzeugter Projekte je Organisation.
`SEED_CLEAR`	`true`, `false`	Entfernt frühere Seed-Daten vor einem Seed-Lauf.

Praktische Regeln

Nutze in Produktion DB_SYNCHRONIZE=false, DB_MIGRATIONS_RUN=true, SWAGGER_ENABLED=false und VITE_ENABLE_DEV_TOOLS=false.
Ändere APP_ORIGIN und CORS_ORIGINS gemeinsam und immer auf die tatsächlich verwendete Browser-Adresse.
Änderungen an VITE_*-Variablen benötigen ein neu gebautes Frontend-Image; reine Backend-Variablen können meist per Container-Neustart wirksam werden.
Bei externer Datenbank müssen Host, Port und TLS-Optionen zur Vorgabe des Datenbank-Hostings passen.

Laufzeit, HTTP und Reverse Proxy​

Datenbank und Migrationen​

Anmeldung, Sitzungen und Sicherheit​

Rate Limits und Listen​

Ersteinrichtung, Branding und Verhalten​

SMTP und E-Mail​

Rechtstexte​

Feature-Flags und Seeds​

Praktische Regeln​