breadcrumb-the-shire/docs/reference-konfiguration.md

Konfiguration (ENV-Variablen)

Letzte Aktualisierung: 2026-04-01

Alle Konfiguration erfolgt über Umgebungsvariablen in der .env-Datei. Vorlage: .env.example — niemals echte Credentials committen.

Setup-Vertrag (Source of Truth): Fuer den Boot wird config/config.php benoetigt; die Datei wird aus config/config.php.example abgeleitet. Diese Seite und web/index.php sind die massgeblichen Referenzen dafuer.

---

App

Variable	Standard	Beschreibung
APP_NAME	CoreCore	Anwendungsname (wird in UI-Titeln und E-Mails verwendet)
APP_URL	http://localhost:8080	Basis-URL der Anwendung (für Links in E-Mails und Redirects)
APP_ENV	dev	Laufzeitumgebung (dev oder prod) — beeinflusst Fehlerausgabe und Caching
APP_DEBUG	true	Debug-Modus aktivieren (true/false) — in Produktion auf false setzen
APP_CONFIG_VALIDATE	true	Boot-Validierung für ENV-Konfiguration aktivieren/deaktivieren (true/false)
APP_TIMEZONE	Europe/Berlin	PHP-Zeitzone für date_default_timezone_set()
APP_STORAGE_PATH	./storage	Pfad zum Storage-Verzeichnis für Uploads und Caches
APP_CRYPTO_KEY	(leer)	Schlüssel für symmetrische Verschlüsselung (64-stelliger Hex-Key oder Base64 mit 32 Byte) — Pflichtfeld in Produktion
APP_LOCALE	de	Standard-Sprache der Anwendung
APP_LOCALES	de,en	Komma-getrennte Liste aller unterstützten Sprachen
APP_I18N_DOMAIN	default	Gettext-Domain — bestimmt welche i18n/default_*.json geladen wird, normalerweise nicht ändern
APP_VENDOR_PHP_ISSUES_MODE	suppress_deprecations	Umgang mit PHP-Deprecations/Warnings aus Vendor-Code. Werte: strict (alle Fehler), suppress_deprecations (Deprecations unterdrücken), suppress_deprecations_warnings (Deprecations + Warnings unterdrücken). In Produktion auf strict setzen

---

Session

Variable	Standard	Beschreibung
SESSION_NAME	CoreCore	Name des Session-Cookies im Browser

---

Tenant

Variable	Standard	Beschreibung
TENANT_SCOPE_STRICT	true	Erzwingt strikte Tenant-Isolation (true/false) — in Produktion immer true

---

Datenbank

Variable	Standard	Beschreibung
DB_HOST	db	Hostname des MySQL/MariaDB-Servers (Docker-Service-Name oder IP)
DB_PORT	3306	Port des Datenbankservers
DB_NAME	db	Name der Datenbank
DB_USER	user	Datenbankbenutzer
DB_PASS	user	Passwort des Datenbankbenutzers
DB_ROOT_PASSWORD	root	Root-Passwort für Docker-Compose (wird nur vom DB-Container genutzt, nicht von PHP)

---

Cache

Variable	Standard	Beschreibung
CACHE_SERVERS	memcached:11211	Memcached-Server als host:port (Docker-Service-Name oder IP)

---

Firewall

Die Firewall begrenzt gleichzeitige Requests pro IP (Concurrency-Schutz).

Variable	Standard	Beschreibung
FIREWALL_CONCURRENCY	10	Max. gleichzeitige Requests pro IP
FIREWALL_SPINLOCK_SECONDS	0.15	Wartezeit in Sekunden zwischen Concurrency-Prüfungen
FIREWALL_INTERVAL_SECONDS	300	Zeitfenster in Sekunden für die Concurrency-Messung
FIREWALL_CACHE_PREFIX	fw_concurrency_	Prefix für Memcached-Keys der Firewall
FIREWALL_REVERSE_PROXY	false	Auf true setzen wenn die App hinter einem Reverse Proxy (Nginx, Traefik) läuft — sonst wird die Proxy-IP statt der echten Client-IP verwendet

---

SMTP (E-Mail)

Variable	Standard	Beschreibung
SMTP_HOST	smtp.example.com	Hostname des SMTP-Servers
SMTP_PORT	587	Port des SMTP-Servers (587 = STARTTLS, 465 = SSL)
SMTP_USER	no-reply@example.com	SMTP-Benutzername / Absenderadresse
SMTP_PASS	(leer)	SMTP-Passwort
SMTP_FROM	no-reply@example.com	Absender-E-Mail-Adresse
SMTP_FROM_NAME	CoreCore	Absendername in ausgehenden E-Mails
SMTP_SECURE	tls	Verschlüsselungstyp: tls (STARTTLS) oder ssl

---

Initiale DB-Settings (Seed)

Beim Fresh-Setup über db/init/init.sql werden zusätzlich folgende Settings in der DB vorbelegt:

• app_title -> CoreCore
• default_tenant_id -> Seed-Mandant MusterMandant
• default_department_id -> Seed-Abteilung mit Code MUSTER
• default_role_id -> Seed-Rolle mit Code USER
• app_locale -> de
• app_registration -> 1 (Self-Registration aktiviert)
• api_token_default_ttl_days -> 90
• api_token_max_ttl_days -> 365
• api_cors_allowed_origins -> http://localhost:8080, http://127.0.0.1:8080
• session_idle_timeout_minutes -> 30
• session_absolute_timeout_hours -> 8
• user_inactivity_deactivate_days -> 180
• user_inactivity_delete_days -> 365
• frontend_telemetry_enabled -> 1
• frontend_telemetry_sample_rate -> 0.2
• frontend_telemetry_allowed_events -> ajax_error,warn_once

Diese Defaults werden von Selbstregistrierung, Admin-Benutzeranlage und Import genutzt, wenn keine expliziten Zuordnungen gesetzt sind.

---

Produktions-Checkliste

Folgende Variablen müssen vor Go-Live angepasst werden:

• APP_ENV=prod
• APP_DEBUG=false
• APP_CRYPTO_KEY — z. B. 64-stelligen Hex-Key generieren: openssl rand -hex 32
• APP_URL — auf die echte Domain setzen
• TENANT_SCOPE_STRICT=true
• FIREWALL_REVERSE_PROXY=true falls hinter Nginx/Traefik
• Alle DB-Credentials auf sichere Werte setzen
• Alle SMTP-Credentials auf echte Werte setzen

---

Boot-Validierung (Fail-Fast)

Beim Start validiert die Anwendung die zentrale ENV-Konfiguration sofort in config/config.php. Bei fehlenden oder ungültigen Pflichtwerten stoppt der Boot-Prozess mit klarer Fehlermeldung.

Geprüft werden unter anderem:

• Pflicht-Keys wie APP_ENV, DB_*, CACHE_SERVERS, SESSION_NAME, FIREWALL_*
• Typen/Formate (bool, int, float, timezone, URL)
• Konsistenz (APP_LOCALE muss in APP_LOCALES enthalten sein)
• Production-Regeln:
  • APP_URL muss gesetzt sein
  • APP_CRYPTO_KEY muss gesetzt und gültig sein (64 Hex oder Base64/32 Byte)
  • APP_DEBUG=false
  • TENANT_SCOPE_STRICT=true

Nur für Notfälle kann die Validierung temporär abgeschaltet werden:

APP_CONFIG_VALIDATE=false

Empfehlung: im Normalbetrieb immer true lassen.