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): `config/config.php` ist im Repository getrackt und liest alle Werte über `$envString()`/`$envInt()`/`$envBool()` aus den ENV-Variablen. 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:

```env
APP_CONFIG_VALIDATE=false
```

Empfehlung: im Normalbetrieb immer `true` lassen.