breadcrumb-the-shire/docs/konfiguration.md

# Konfiguration (ENV-Variablen)

Letzte Aktualisierung: 2026-02-21

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

---

## App

| Variable | Standard | Beschreibung |
|---|---|---|
| `APP_NAME` | `App` | 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 |

---

## Session

| Variable | Standard | Beschreibung |
|---|---|---|
| `SESSION_NAME` | `app_session` | 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` | `imvs` | Name der Datenbank |
| `DB_USER` | `imvs` | Datenbankbenutzer |
| `DB_PASS` | `imvs` | Passwort des Datenbankbenutzers |
| `DB_ROOT_PASSWORD` | `imvs_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` | `App` | Absendername in ausgehenden E-Mails |
| `SMTP_SECURE` | `tls` | Verschlüsselungstyp: `tls` (STARTTLS) oder `ssl` |

---

## 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.