tbh/breadcrumb-the-shire
1
0
Fork 0
forked from fa/breadcrumb-the-shire
Code Pull Requests Activity
Files
52f10ae46c314b9d3029c6bda40523d945b21710
breadcrumb-the-shire/docs/reference-konfiguration.md
fs 149d4515de refactor(settings): remove global appearance settings — tenant is sole source 
Removes the global app_theme, app_theme_user and app_primary_color settings
from the admin/settings area and the underlying service/cache/API/i18n/docs
layers. The tenant columns (tenants.primary_color, default_theme,
allow_user_theme) become the single source of truth for appearance.
Branding helpers are tenant-only and fall back to a hardcoded 'light' theme
with no brand color when no tenant context is available (login, error,
pre-session pages). The APP_THEME env var is removed.

Scope:
- UI: Appearance tab gone from /admin/settings; tenant edit form drops the
  global-fallback color preview.
- Service: SettingsAppGateway no longer exposes setting-backed accessors
  for theme/user-theme/primary-color. Theme catalog utilities (listThemes,
  isAllowedTheme, normalizeTheme, resolveDefaultTheme) stay and are used
  across Tenant / Auth / User flows; resolveDefaultTheme now hardcodes
  'light' with a catalog fallback (no global/env lookup).
- AdminSettingsService: buildPageData, sanitization, audit snapshot, apply
  step and cache payload are all stripped of the three keys. Dead helper
  applyAppPrimaryColor + normalizePrimaryColor removed.
- Cache: SettingCacheService HOT_PATH_KEYS drops the three keys.
- API: /settings (GET/PUT) and /settings/public (GET) no longer expose
  appearance fields; OpenAPI schemas pruned accordingly.
- Audit redaction list shortened.
- DB: db/init/init.sql seed rows removed. No migration for existing
  installs — legacy rows stay inert.
- i18n + docs: setting.app_theme, setting.app_theme_user,
  setting.app_primary_color removed from de+en locales; reference and
  explanation docs updated.
- Tests: covering tests for the removed methods pruned; ThemeResolutionTest
  rewritten for tenant-only semantics. One unrelated PHP-CS-Fixer issue in
  UserRegistrar.php cleaned up to keep QG-006 green.

Workflow: .agents/runs/SETTINGS-APPEARANCE-TENANT-ONLY/ (gitignored).
Gates: QG-001..003, QG-006, QG-008 all pass (1985 tests, 28764 assertions).
Reviews: code, security, acceptance all pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 22:40:15 +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): 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.

View Git Blame Copy Permalink