Deployment
Produktions-Build, Docker, BoxLang MiniServer und eine Go-Live-Checkliste.
Auf dieser Seite
Deployment
Produktions-Build
npm run build
Kompiliert und versieht das Frontend mit Fingerprints nach public/includes/ - siehe Frontend.
Docker
Ein Dockerfile und datenbankspezifische Compose-Dateien liegen in resources/docker/. MySQL ist der Standard; PostgreSQL- und MSSQL-Alternativen werden für die anderen CI-getesteten Ziele bereitgestellt. MariaDB kann die MySQL-Konfiguration und den mysql-JDBC-Treiber nutzen. box.json definiert außerdem die Skripte docker:build, docker:run, docker:bash und docker:stack (ausführen mit box run-script <name>) als Abkürzungen für die unten stehenden Einzel-Argument-Befehle - sie ersetzen nicht die erforderliche BoxLang-CLI-Installation für lokale box-Befehle und stehen in keinem Zusammenhang mit npm run (es gibt kein npm run docker:*).
Lokale Entwicklung mit Docker Compose
resources/docker/docker-compose.yml führt die App (gebaut aus resources/docker/Dockerfile.dev, das CommandBox nativ auf dem offiziellen ortussolutions/boxlang:cli-Image installiert, damit die Engine-Version zu .bvmrc passt) zusammen mit einem MySQL-8-Container aus, wobei das gesamte Repo in den App-Container gemountet wird, sodass Änderungen auf dem Host ohne Rebuild wirksam werden - keine lokale BoxLang/MySQL-Installation erforderlich. Führe docker compose direkt aus (statt über das docker:stack-Paketskript), damit mehrteilige Befehle wie up -d korrekt durchgereicht werden:
npm install
npm run build
docker compose -f resources/docker/docker-compose.yml up -d
docker compose -f resources/docker/docker-compose.yml exec coldbox_app box install
docker compose -f resources/docker/docker-compose.yml exec coldbox_app box migrate up
docker compose -f resources/docker/docker-compose.yml exec coldbox_app box migrate seed run
Besuche http://127.0.0.1:8080. MySQL ist vom Host aus unter 127.0.0.1:3406 erreichbar (gewählt, um Kollisionen mit einem bereits auf 3306 laufenden MySQL/MariaDB zu vermeiden); der App-Container spricht über das interne Docker-Netzwerk mit MySQLs echtem Port 3306.
Die Compose-Datei startet Vite nicht - starte es separat auf dem Host für HMR:
npm install
npm run dev
Eine MSSQL-spezifische Compose-Datei ist ebenfalls verfügbar zum Testen gegen SQL Server 2022. Sie installiert den bx-mssql-Treiber im App-Container, erstellt die cbgenesis-Datenbank und hält ihre Daten unter resources/docker/.db/mssql/:
npm install
npm run build
docker compose -f resources/docker/docker-compose.mssql.yml up -d
docker compose -f resources/docker/docker-compose.mssql.yml exec coldbox_app box install
docker compose -f resources/docker/docker-compose.mssql.yml exec coldbox_app box migrate up
docker compose -f resources/docker/docker-compose.mssql.yml exec coldbox_app box migrate seed run
Die Anwendung bleibt unter http://127.0.0.1:8080 erreichbar; SQL Server ist vom Host aus unter 127.0.0.1:1434 erreichbar. Das Standard-Passwort für sa ist nur für lokale Tests gedacht. Setze MSSQL_SA_PASSWORD, bevor du den Stack startest, um es zu überschreiben. Stoppe diesen Stack mit:
docker compose -f resources/docker/docker-compose.mssql.yml down
Die PostgreSQL-Alternative verwendet PostgreSQL 16, veröffentlicht den Host-Port 5433 und installiert bx-postgresql automatisch:
npm install
npm run build
docker compose -f resources/docker/docker-compose.postgresql.yml up -d
docker compose -f resources/docker/docker-compose.postgresql.yml exec coldbox_app box install
docker compose -f resources/docker/docker-compose.postgresql.yml exec coldbox_app box migrate up
docker compose -f resources/docker/docker-compose.postgresql.yml exec coldbox_app box migrate seed run
Die Standard-MySQL-Compose-Datei bleibt unverändert. Stoppe jede der beiden Alternativen mit ihrer jeweiligen Compose-Datei und down.
docker compose -f resources/docker/docker-compose.yml down
Produktions-Image
box run-script docker:build
box run-script docker:run
Baue das Frontend, bevor du ein Produktions-Image erstellst:
npm run build
BoxLang MiniServer
Eine Alternative zum bx-cli-Entwicklungsserver, um die kompilierte App direkt auszuführen:
cd my-app
boxlang-miniserver --port 8080 --webroot ./public --dev
Der MiniServer bietet kein box install, keine Migrationen und keine TestBox-Befehle. Verwende dafür die erforderliche BoxLang CLI.
Produktions-Checkliste
ENVIRONMENT=production und BOXLANG_DEBUG=false in .env.
Richte app/config/modules/cbmailservices.bx auf einen echten SMTP-/Postmark-/SendGrid-Treiber aus - siehe E-Mail.
Der Seeder erstellt admin@cbgenesis.com / test, als reset-pending markiert. Die Anmeldung damit gewährt keine Session: Du wirst direkt zum Formular für die Passwort-Zurücksetzung weitergeleitet und musst zuerst ein neues Passwort setzen. Der Bootstrap-Hash ist öffentlich (er wird im Repo mitgeliefert), also niemals diese Markierung löschen, um weiterhin test zu verwenden. Siehe Erste Schritte.
reinitPassword liest COLDBOX_REINIT_PASSWORD aus der Umgebung. Lass es in der Produktion nicht gesetzt, dann fällt jeder Boot auf eine frische zufällige UUID zurück, die niemand kennt, was ?fwreinit vollständig schließt. Setze es nur, wenn du eine laufende Instanz reinitialisieren musst, und behandle es wie ein Credential. Es auf einen leeren String zu setzen, lässt die Reinitialisierung für jeden offen, weshalb development() genau das tut und die Produktion es nicht darf.
Über SSL-Konfiguration in server.json oder deinen Reverse-Proxy/Load-Balancer der Wahl.
cbTrustProxyHeaders ist standardmäßig aktiviert, passend zu einem typischen Deployment hinter einem Reverse-Proxy oder Load-Balancer. Falls die App stattdessen direkt am Internet hängt, schalte es aus - siehe Deployment hinter einem Reverse-Proxy. Dies falsch herum zu haben, hebelt entweder das Rate-Limiting aus oder bricht es für alle hinter dem Proxy.
app/config/modules/cbsecurity-passkeys.bx wird mit reinen Entwicklungs-Platzhaltern ausgeliefert (relyingPartyId: "localhost", allowedOrigins: ["http://localhost:8080"]). Setze diese vor dem Go-Live auf deine echte Produktionsdomain, sonst schlägt die Passkey-Registrierung fehl - siehe Sicherheit & Berechtigungen.
npm run build für minifizierte, mit Fingerprints versehene Assets.
Entferne oder beschränke den öffentlichen /healthcheck-Endpunkt, falls er von außerhalb deiner Infrastruktur nicht erreichbar sein sollte.
Deployment hinter einem Reverse-Proxy
RateLimiter, der Audit-Trail und die "Zurücksetzung angefordert von IP"-Sicherheits-E-Mails lesen die IP des Aufrufers alle über cbsecuritys getRealIP(). Diese Funktion hat zwei mögliche Quellen für die IP, und nur du - die Person, die diese App deployt - weißt, welche für dein Setup korrekt ist:
- Die rohe Socket-Adresse (
cgi.remote_addr) - korrekt, wenn die App direkt am Internet hängt. Sitzt ein Reverse-Proxy davor, ist dies immer die Adresse des Proxys, nicht die des Besuchers. - Die Request-Header
X-Forwarded-For/X-Cluster-Client-IP- korrekt nur, wenn etwas vor der App (nginx, ein Load-Balancer, ein CDN) jeden vom Client gesendeten Wert entfernt und den Header selbst setzt. Tut das nichts, kann jeder Aufrufer diesen Header auf beliebige Werte setzen, sogar auf einen anderen bei jedem Request.
Die Einstellung cbTrustProxyHeaders (Standard true, editierbar unter /settings) wählt zwischen beiden. Sie eingeschaltet zu lassen, wenn du gar nicht hinter einem Proxy sitzt, der den Header bereinigt, öffnet genau die Rate-Limit-Umgehung wieder, die sie eigentlich schließen soll - ein Aufrufer kann bei jedem Login-Versuch einen neuen X-Forwarded-For-Wert fälschen und nie blockiert werden. Sie auszuschalten, wenn du tatsächlich hinter einem solchen Proxy sitzt, bedeutet, dass jeder Besucher sich die IP des Proxys teilt - ein blockierter Aufrufer blockiert alle dahinter, und der Audit-Trail zeichnet für jede Aktion die Adresse des Proxys auf.
Wenn du direkt am Internet hängend deployst, ohne irgendetwas vor der App, schalte das aus. Wenn du hinter einem Reverse-Proxy deployst, bestätige, dass er X-Forwarded-For tatsächlich überschreibt (statt einen vom Client gelieferten Wert anzuhängen oder durchzureichen), bevor du dies eingeschaltet lässt.