Deployment & Secrets

Paketierung in .bxa, und warum Secrets nie im generierten Quellcode landen.

Deployment & Secrets

Secrets gelangen nie in das Artefakt - sie werden dem Prozess bereitgestellt, ganz rechts in dieser Kette:

flowchart LR
    P["your project"] -->|"bxAgents build"| B[".build/app/<br/>a plain ColdBox app"]
    B -->|"bxAgents package"| A["dist/name-version.bxa<br/>+ .sha256 + redacted manifest.json"]
    A -->|"bxAgents deploy"| T["a target:<br/>local / ssh / ftp / sftp<br/>docker / digitalocean"]
    T --> RUN["boxlang-miniserver runs the unzipped app"]
    ENV["environment variables<br/>OPENAI_API_KEY, ANTHROPIC_API_KEY,<br/>every *EnvVar a gateway names"] -->|"read at RUNTIME by bx-ai"| RUN

    style A fill:#eaf6ec,stroke:#155724
    style ENV fill:#fff3cd,stroke:#856404

Nichts links von ENV trägt jemals einen Secret-Wert: .env/Dotfiles sind bedingungslos vom Zip ausgeschlossen, und das Manifest ist zusätzlich geschwärzt, obwohl es ohnehin nie einen enthält.

Paketierung

bxAgents package zippt .build/app/ in ein portables .bxa-Artefakt:

bxAgents package --version=1.0.0

erzeugt, in dist/:

• {agentName}-{version}.bxa - die gezippte App
• {agentName}-{version}.bxa.sha256 - ihre Prüfsumme
• manifest.json - eine geschwärzte Kopie des Build-Manifests (siehe unten)

Zweimal hintereinander über denselben Build zu paketieren erzeugt bytegleiche Zip-Daten (deterministische Eintragsreihenfolge/Zeitstempel) - nützlich, um zu prüfen, dass ein in CI gebautes Artefakt einem lokal gebauten entspricht.

package erfordert einen vorherigen build (es liest .build/manifest.json) und verweigert die Ausführung - ohne eine .bxa zu erzeugen -, falls manifestVersion nicht gesetzt oder fehlerhaft ist.

Dateien ausschließen: .bxaignore

Ein optionales .bxaignore im Projekt-Root, ein Glob-Muster pro Zeile (mit # beginnende Zeilen sind Kommentare), schließt passende Pfade aus der paketierten .bxa aus:

# .bxaignore
*.log
scratch/

Das kommt zusätzlich zu einem fest eingebauten, immer aktiven Ausschluss von .env/.env.*/Dotfiles auf der Paketierungsebene - selbst wenn .bxaignore sie nicht erwähnt, und selbst wenn sie irgendwie in .build/app gelandet sind, schaffen sie es nie ins Zip.

Secret-Schwärzung

Secrets werden von vornherein nie in manifest.json geschrieben - der agent-Block des Manifests enthält ausschließlich sichere, strukturelle Felder (name, description, model, environment). Als zusätzliche Verteidigungsebene durchläuft package das Manifest zudem rekursiv und ersetzt jeden Struct-Schlüssel, der wie ein Secret aussieht, durch [REDACTED]:

(apikey | api_key | token | secret | password)$   (case-insensitive, any prefix)

Das schützt vor einem zukünftigen Feld - oder einem Aufrufer, der auf anderem Weg eine reichhaltigere Struktur an package übergibt -, das versehentlich einen Wert preisgibt, auch wenn das heutige Manifest von vornherein nie einen dort ablegt.

Wo echte Secrets leben

BX Agents löst Provider-API-Schlüssel, Tokens oder Passwörter nie auf, speichert sie nicht und bettet sie nirgendwo in einem Build oder Paket ein. Das ist ausschließlich bx-ais eigene Aufgabe, zur Laufzeit: Es liest sie aus der Prozessumgebung gemäß seiner eigenen <PROVIDER>_API_KEY-artigen Konvention (z. B. OPENAI_API_KEY, ANTHROPIC_API_KEY). Sie werden so gesetzt, wie Secrets für einen deployten Prozess sonst auch verwaltet werden - eine OS-Umgebungsvariable, eine vom Prozessmanager geladene .env-Datei (nie committet, nie paketiert), oder der Secret-Manager der eigenen Plattform.

export OPENAI_API_KEY=sk-...
bxAgents serve

Ausliefern

bxAgents deploy --destination=/path/to/somewhere   # lokal, Flag-Kurzform
bxAgents deploy --name=production                  # jedes Ziel, über deploy/production.bx

Sechs pluggable Ziele sind sofort einsatzbereit - local (die neueste .bxa irgendwohin kopieren), ssh (an einen nackten Server ausliefern), ftp/sftp (über das echte Modul bx-ftp ausliefern, eine echte Laufzeitabhängigkeit dieses Projekts), docker (ein Container-Image bauen/pushen) und digitalocean (an eine DigitalOcean-App-Platform-App deployen) - siehe deploy/ für die vollständige Konfigurationsform jedes einzelnen und CLI-Referenz für die CLI-Flags.

Kein Ziel liest je ein Secret aus der deploy/*-Konfiguration - Zugangsdaten (Registry-Passwörter, SSH-Schlüssel, das DigitalOcean-API-Token) werden zur Deploy-Zeit immer aus Umgebungsvariablen aufgelöst, dieselbe Regel "Secrets bleiben extern" wie überall sonst in diesem Dokument. Siehe deploy/ für die genaue Umgebungsvariable, die jedes Ziel erwartet.

Um eine paketierte .bxa manuell woanders auszuführen: entpacken (es ist eine gewöhnliche ColdBox-App) und boxlang-miniserver auf das entpackte Verzeichnis richten, dabei alle für dieses Deployment nötigen geheimen Umgebungsvariablen setzen.