Quick Start

Get Buzen ESB running in under 15 minutes.

This page gets a new environment to a running ESB instance, authenticated API access, and first route deployment. For deeper architecture and behavior, continue to the linked guides.

1. Prerequisites

Java 21+
Maven 3.9+
Docker (optional, recommended for runtime packaging)
Ports available: 8443 (runtime) and optional 8080 (redirect/http depending config)

2. Build the project

git clone https://github.com/buzen/buzen-esb.git
cd buzen-esb
mvn clean install

If you are making frontend changes in buzen-console/frontend, run:

cd buzen-console/frontend
npx react-doctor

3. Run as standalone JAR

Build runtime jar then run with a persistent encryption key.

mvn -pl buzen-runtime -am clean package -DskipTests
export BUZEN_ESB_ENCRYPTION_KEY=$(openssl rand -base64 32)
java -jar buzen-runtime/target/buzen-esb.jar

Runtime home defaults to ./buzen-esb if no explicit env override is provided. It will hold data, logs, deployments, and work directories.

4. Run with Docker

BUZEN_ESB_IMAGE=buzentech/buzen-esb
BUZEN_ESB_VERSION=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)

mvn -pl buzen-runtime -am clean package -DskipTests
docker build -f docker/Dockerfile -t ${BUZEN_ESB_IMAGE}:${BUZEN_ESB_VERSION} buzen-runtime/target

export BUZEN_ESB_ENCRYPTION_KEY=$(openssl rand -base64 32)

docker run --name buzen-esb \
  -p 8443:8443 \
  -e BUZEN_ESB_ADMIN_PASSWORD=admin \
  -e BUZEN_ESB_ENCRYPTION_KEY=${BUZEN_ESB_ENCRYPTION_KEY} \
  -v buzen-data:/opt/buzen-esb/data \
  -v buzen-deployments:/opt/buzen-esb/deployments \
  -v buzen-lib:/opt/buzen-esb/lib \
  -v buzen-work:/opt/buzen-esb/work \
  ${BUZEN_ESB_IMAGE}:${BUZEN_ESB_VERSION}

5. First authentication

Default management auth flow issues bearer tokens.

TOKEN=$(curl -ksS -X POST https://<esb-host>:8443/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' | jq -r '.data.accessToken')

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

6. Deploy your first app

Create a minimal .bar archive:

my-first.bar
|- buzen.json
|- routes/
   |- hello.yaml

{
  "name": "my-first-app",
  "version": "1.0.0",
  "routes": [
    { "file": "routes/hello.yaml", "autoStart": true }
  ]
}

- route:
    id: hello-route
    from:
      uri: "timer:hello?period=5000"
      steps:
        - log:
            message: "Hello from Buzen ESB"

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

7. Verify runtime status

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

Next recommended pages: Deployment and Packaging, YAML Authoring, and Management API.