Konfiguration
Umgebungsvariablen, Framework-Einstellungen und modulspezifische Konfiguration.
Auf dieser Seite
Konfiguration
Umgebungsvariablen
Kopiere .env.example nach .env und trage deine eigenen Werte ein - überall in der App abrufbar über getSystemSetting( "VAR_NAME", "default" ):
| Variable | Zweck |
|---|---|
APPNAME | Anzeigename der Anwendung |
ENVIRONMENT | development oder production |
ASSET_URL | Öffentliches URL-Präfix für Vite-Produktions-Assets (Standard /includes) |
BOXLANG_DEBUG | Aktiviert die BoxLang-Debug-Ausgabe |
DB_CONNECTIONSTRING | Vollständiger JDBC-Connection-String |
DB_DRIVER | Datenbanktreiber, klein geschrieben, passend zu einem bx-*-JDBC-Treibermodul (mysql für MySQL oder MariaDB, mssql, postgresql, h2, oracle, sqlite) - onServerInitialInstall in server.json installiert bx-${DB_DRIVER} beim ersten Serverstart |
DB_HOST / DB_PORT / DB_DATABASE | Datenbankverbindungsdetails |
DB_SCHEMA | Schema, das der Migrations-Runner anzielt (.cbmigrations.json); bei Engines ohne Schema leer lassen |
DB_USER / DB_PASSWORD | Datenbank-Zugangsdaten |
JWT_SECRET | Signierschlüssel für cbsecuritys JWT-Unterstützung |
COOKIE_ENCRYPTION_KEY | Verschlüsselungsschlüssel für cbstorages' Cookie-Speicher. Spielt erst eine Rolle, sobald useEncryption aktiviert wird (standardmäßig aus) - setze ihn, bevor du das tust, sonst wird der Schlüssel bei jedem Boot neu generiert und macht zuvor verschlüsselte Cookies stillschweigend ungültig |
CBFS_ASSETS_DISK_PATH | Dateisystempfad für die cbfs-assets-Disk, die Avatare und das Branding-Logo speichert (Standard <app-root>/.cbfs) |
COLDBOX_REINIT_PASSWORD | Passwort, das ?fwreinit erfordert. Nicht gesetzt bedeutet ein frischer zufälliger Wert pro Boot, sodass die Reinitialisierung geschlossen ist - siehe Deployment |
COLDBOX_SESSION_TIMEOUT | Session-Cache-Timeout in Minuten für cbstorages' Session-Speicher (Standard 60) |
Framework-Einstellungen (app/config/Coldbox.bx)
| Einstellung | Wert |
|---|---|
defaultEvent | Auth.login — nicht authentifizierte Besucher landen auf der Login-Seite |
requestStartHandler | Main.onRequestStart |
applicationStartHandler | Main.onAppInit |
exceptionHandler | Main.onException |
modulesExternalLocation | ["/modules"] |
autoMapModels | true |
jsonPayloadToRC | true |
reinitPassword | COLDBOX_REINIT_PASSWORD, oder eine frische zufällige UUID pro Boot, wenn das nicht gesetzt ist |
Eine development()-Umgebungs-Override aktiviert das Whoops-Fehler-Template, den WireBox-Singleton-Reload, den ColdBox-Debug-Modus und leert reinitPassword, sodass ?fwreinit=1 lokal ohne eines funktioniert. LogBox ist mit einem Konsolen-Appender plus einem rollierenden Datei-Appender konfiguriert, der nach app/logs schreibt.
App-Einstellungen vs. Framework-Konfiguration
Zwei verschiedene Dinge liegen beide unter app/config/, und es ist leicht, sie zu verwechseln:
Framework-Konfiguration (Coldbox.bx, Router.bx, WireBox.bx, CacheBox.bx, Scheduler.bx) ist statisch, dateibasiert, und Änderungen wirken beim nächsten ?fwreinit.
App-Einstellungen (cbAppName, cbAllowRegistration, cbMinPasswordLength, ...) sind DB-gestützt, admin-editierbar unter /settings, definiert in SettingService.static.DEFAULTS, und mit einer TTL von 2 Stunden gecacht.
SettingService.preFlightCheck() (aufgerufen aus Main.onAppInit) sät beim Boot jeden fehlenden Standardwert in die Datenbank, sodass es genügt, einen neuen Schlüssel zu DEFAULTS hinzuzufügen, damit er erscheint. Eine Einstellung kann auch auf zwei weitere Arten überschrieben werden, beide gelesen von loadConfigOverrides()/loadEnvironmentOverrides():
- Jeder mit
cb*präfixierte Schlüssel inColdbox.bxsvariables.settings - Jede mit
genesis_*präfixierte Umgebungsvariable
Modulkonfiguration
Jedes installierte Modul hat seine eigene Einstellungsdatei unter app/config/modules/:
| Modul | Wichtige Einstellungen |
|---|---|
| cbsecurity | cbauth-Provider, CSRF (rotierend, 30 Min), Firewall mit @secured-Annotation-Scanning, Sicherheits-Header, JWT (HS512, 60 Min) — siehe Sicherheit & Berechtigungen |
| cbauth | UserService als Identity-Provider, cachebasierter Session-Speicher |
| cbmailservices | BXMail-Protokoll in der Produktion, Files-Protokoll in der Entwicklung — siehe E-Mail |
| cborm | Entity-Injection aktiviert, Pagination maxRows: 25 / maxRowsLimit: 500 |
| cbfs | assets-Disk (Local-Provider standardmäßig, Pfad aus CBFS_ASSETS_DISK_PATH) - speichert Avatare und das Branding-Logo, ausgeliefert von Assets.bx — siehe Frontend |
| cbstorages | Cache-Speicher (Sessions-Cache, Timeout aus COLDBOX_SESSION_TIMEOUT, Standard 60 Min), Cookie-Speicher (Verschlüsselung standardmäßig aus) |
| cbsecurity-passkeys | WebAuthn-Relying-Party-Konfiguration für die Passkey-Anmeldung - relyingPartyId/allowedOrigins sind Platzhalterwerte localhost, die du vor der Produktion ändern musst, siehe Deployment |
| mementifier | ISO8601-Daten, ORM-Auto-Includes, UTC-Konvertierung |