Deployment and Packaging - Buzen ESB Docs

1. Deployment model

Applications are loaded into the runtime from:

buzen-esb/deployments/ directory (file-drop/hot deploy)
Management API POST /api/v1/apps (multipart upload)
Template deployment workflows

Runtime extraction and execution happen in work/{appId}. Canonical archives remain in deployments/.

2. Canonical .bar archive layout

my-integration.bar
|- buzen.json
|- routes/
|  |- main-route.yaml
|- config/
|  |- application.yml
|- lib/
   |- custom-transform.jar

Accepted deployment extensions: .bar and .zip.

Use explicit buzen.json even though runtime can synthesize manifests for legacy/simple archives.

3. Manifest specification (buzen.json)

Field	Required	Description
name	Yes	Application name, normalized into app ID
version	No	Semantic version (default 1.0.0)
routes[]	Yes*	Route files with per-route autoStart and optional ID override
config.file	No	YAML/properties config to flatten into app property source
libraries[]	No	App-local libraries loaded into app classloader
properties	No	Inline property overrides
dependencies[]	No	Declared app dependencies

* JSON create-empty-app flow is the only standard path where no routes can be initially present.

{
  "name": "customer-integration",
  "version": "1.2.0",
  "description": "Customer synchronization",
  "routes": [
    { "file": "routes/sync-customers.yaml", "autoStart": true },
    { "file": "routes/reconcile-orders.yaml", "autoStart": false, "id": "orders-reconcile" }
  ],
  "config": { "file": "config/application.yml" },
  "libraries": ["lib/custom-transform.jar"],
  "dependencies": [
    { "name": "shared-http", "version": "1.0.0" }
  ],
  "properties": {
    "partner.base-url": "https://partner.example.com"
  }
}

Schema: buzen-archive-manifest.schema.json

4. Deployment methods

A. API upload (CI/CD preferred)

curl -ksS -X POST https://<esb-host>:8443/api/v1/apps \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "file=@my-integration.bar"

B. Directory drop (hot deploy)

cp my-integration.bar /opt/buzen-esb/deployments/

C. Create empty app shell

curl -ksS -X POST https://<esb-host>:8443/api/v1/apps \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"new-app","description":"empty shell"}'

5. Lifecycle operations

Action	Endpoint	Notes
List apps	GET /api/v1/apps	Includes app status and route counts
Start app	POST /api/v1/apps/{appId}/start	Starts all app routes
Stop app	POST /api/v1/apps/{appId}/stop	Stops routes and marks intentional stop
Redeploy app	POST /api/v1/apps/{appId}/redeploy	Undeploy + deploy from canonical archive
Undeploy app	DELETE /api/v1/apps/{appId}	Removes routes and extracted workspace
Export app	GET /api/v1/apps/{appId}/export	Downloads current archive snapshot

6. Versioning and rollback

Buzen exposes app version and history endpoints for audit-safe rollback workflows:

curl -ksS https://<esb-host>:8443/api/v1/apps/{appId}/versions \
  -H "Authorization: Bearer ${TOKEN}" | jq .

curl -ksS -X POST https://<esb-host>:8443/api/v1/apps/{appId}/rollback \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"targetVersion":"1.0.1"}' | jq .

Use GET /api/v1/apps/{appId}/history for deployment history and operator timeline.

7. Hot deploy behavior

File events are debounced to avoid duplicate processing.
Modify events use checksums to skip no-op redeploys.
Archive delete events trigger undeploy of the owning app.
Route and ingress conflicts fail fast and return descriptive errors.

Auto-start rule: effectiveAutoStart = deployment.autoStart && routeEntry.autoStart.

8. Validation rules and failure conditions

Archive must be non-empty and contain valid route files.
Manifest paths cannot escape archive root (no traversal).
Route IDs must be unique across active runtime.
Ingress paths cannot collide with reserved internal prefixes.
Unsupported file types in route list are rejected.

Treat deployment failures as non-retryable until payload or archive defects are corrected.

Reference details: bar-archive-spec.md