Setup and Runtime Model
This page describes how Buzen ESB boots, loads artifacts, keeps state, and enforces runtime safety. Use it as your source for deployment predictability and incident recovery design.
1. Embedded components
| Subsystem | Implementation | Default behavior |
|---|---|---|
| Execution engine | Apache Camel 4.x | Runs YAML/XML/Java routes |
| Application framework | Spring Boot 4.x | Auto-config, lifecycle, dependency wiring |
| Database | SQLite (embedded) | ${buzen.esb.data-dir}/buzen.db |
| Messaging | Artemis JMS (embedded) | JMS support in-process |
| Metrics/health | Actuator + Micrometer | System and route metrics APIs |
| Management | REST API + Console | /api/v1 and /console |
2. Runtime home and directory model
Runtime path resolution order:
- Explicit override: BUZEN_ESB_HOME / buzen.esb.runtime-home
- Environment-derived defaults (production, staging, development, test, qa)
- Fallback: ./buzen-esb
buzen-esb/
|- deployments/ # canonical .bar files
|- work/ # extracted app content, managed by runtime
|- lib/ # shared runtime jars
|- data/ # sqlite, logs, audit, trace assets3. Startup sequence
- Spring context initializes configuration and security filters.
- SQLite datasource and Flyway migrations execute.
- Connector modules auto-register components.
- Route sources load from classpath/file locations.
- Archive deployer scans deployments and restores apps.
- Ingress validation blocks reserved-path collisions.
- Management endpoints and console become available.
If a previously persisted app is in STOPPED, reload keeps routes stopped on restart.
4A. Route loader path
Classpath/File YAML loading
- Controlled by buzen.esb.routes.locations
- Supports .yaml and .yml
- Uses Camel YamlRoutesBuilderLoader
- Optional hot reload
4B. Archive deployer path
.bar deployment loading
- Watches deployments/ for .bar/.zip
- Extracts to work/{appId}
- Loads routes, config, properties, libraries
- Applies per-route autoStart
5. Application lifecycle states
| Status | Meaning |
|---|---|
| DEPLOYING | Archive validation/extraction/loading in progress |
| DEPLOYED | App loaded but routes not actively running |
| RUNNING | One or more routes are started |
| STOPPED | Routes intentionally stopped |
| FAILED | Deployment or lifecycle action failed |
| UNDEPLOYING | Teardown in progress |
| UNDEPLOYED | App removed from runtime |
6. Route lifecycle behavior
Route operations exposed by management API:
- Start: POST /api/v1/routes/{routeId}/start
- Stop: POST /api/v1/routes/{routeId}/stop
- Suspend: POST /api/v1/routes/{routeId}/suspend
- Resume: POST /api/v1/routes/{routeId}/resume
Routes in an app marked STOPPED are blocked from ad-hoc route-level start operations until app state is resumed.
7. Ingress validation and reserved prefixes
Runtime rejects routes that bind under internal platform paths. Reserved prefixes include management API, actuator, console, websocket, and API docs paths.
/api/v1
/actuator
/console
/ws
/api-docs
/swagger-ui
/v3/api-docs
(+ custom buzen.esb.security.internal-api.reserved-paths)Ingress collisions fail deployment/update and conflicting routes are not kept active.
8. Operational notes
- SQLite uses WAL and conservative pool sizing for lock stability.
- Use persistent volumes for data/, deployments/, and work/ in containers.
- Prefer archive deployments for deterministic release history.
- Use API-level route edits for fine-grained updates without full app replacement.
Continue with Deployment and Packaging and Management API.