tbh/breadcrumb-the-shire
1
0
Fork 0
forked from fa/breadcrumb-the-shire
Code Pull Requests Activity
Files
0c78dc4355bfa6da54585c03730ba50c719f1204
breadcrumb-the-shire/docs/reference-konfiguration.md
fs 0c78dc4355 chore(setup): track config.php directly, slim README to setup checklist 
config/config.php was gitignored and devs had to copy it from
config/config.php.example on every fresh clone. Since the bootstrap
config reads everything from .env via $envString() / $envInt() /
$envBool() defaults, there is nothing developer-specific in the file —
the cp step was dead ceremony.

- Remove config/config.php from .gitignore and track it directly
- Delete config/config.php.example
- Drop the example-existence + per-doc reference checks from
  bin/docs-drift-check.sh; add a legacy-pattern check that flags
  any new mention of the removed example file
- Update ConfigContractsTest to require config.php and forbid the
  example
- Clean stale references in CLAUDE.md, README.md, six docs files,
  and the core-guardrails skill

Same commit slims README down from 294 to 47 lines: one setup
checklist (now 3 commands instead of 4), the seeded login table,
the three quality-gate commands, and pointers to CLAUDE.md and
docs/index.md for everything else.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 08:37:45 +02:00

6.3 KiB
Raw Blame History

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:

APP_CONFIG_VALIDATE=false

Empfehlung: im Normalbetrieb immer true lassen.

View Git Blame Copy Permalink