Get started with Enterprise Service Bus

Prerequisites

• Docker and Docker Compose (v2.23 or later)
• A PhronIQ deployment package and licence key (see below)

Start the stack

ESB ships as a licensed artifact, not as source. After your order, PhronIQ delivers a deployment package — the esb container image plus the docker-compose.yml bundle — and a PhronIQ-signed licence key.

1. Unpack the deployment package and change into its directory.
2. Install the licence key before the first start: point licence.file in config.yaml at the key file you were issued (or set ESB_LICENCE_FILE / ESB_LICENCE_KEY). The daemon verifies the key at startup and refuses to start without one (licence-missing). The Deployment guide’s Licence key section has the details.
3. Start the stack:

docker compose up -d

This starts:

• ESB on http://localhost:8080
• Admin Console on http://localhost:8080/admin
• PostgreSQL on localhost:5432
• Vault on localhost:8200 (development mode; holds the secrets that routes reference)
• Prometheus on localhost:9090
• Grafana on localhost:3000 (dashboards; see Step 5)

The package also starts Kafka and Flink containers. They support the local environment only; ESB does not use them for the features described in this guide.

Verify:

curl http://localhost:8080/healthz
# → ok

Step 1: Configure three services

Edit config.yaml or use the admin console at http://localhost:8080/admin:

services:
  - id: orders
    name: Order Service
    operations: [create, lookup, update]
  - id: inventory
    name: Inventory Service
    operations: [check, reserve, release]
  - id: notifications
    name: Notification Service
    operations: [send]

Step 2: Create two flows

Flow 1: Order Processing

flows:
  - id: order-processing
    version: "1.0"
    entry_step: step_create_order
    steps:
      - id: step_create_order
        type: call
        service: orders
        operation: create
        next: step_check_inventory

      - id: step_check_inventory
        type: call
        service: inventory
        operation: check
        next: step_branch

      - id: step_branch
        type: branch
        condition:
          path: $.inventory.available
          equals: true
        on_true: step_reserve
        on_false: step_notify_backorder

      - id: step_reserve
        type: call
        service: inventory
        operation: reserve
        next: step_notify

      - id: step_notify_backorder
        type: call
        service: notifications
        operation: send
        end: true

      - id: step_notify
        type: call
        service: notifications
        operation: send
        end: true

Flow 2: Data Sync (with aggregation)

  - id: data-sync
    version: "1.0"
    entry_step: step_fetch
    steps:
      - id: step_fetch
        type: call
        service: orders
        operation: lookup
        next: step_transform

      - id: step_transform
        type: transform
        transform: json_to_uppercase
        next: step_aggregate

      - id: step_aggregate
        type: aggregate
        aggregate:
          strategy: object_merge
          timeout: 10s
          calls:
            - alias: orders_data
              service: orders
              operation: lookup
            - alias: inventory_data
              service: inventory
              operation: check
        end: true

Step 3: Create a Policy

policies:
  - id: rate-limit-orders
    name: Order Rate Limit
    scope: service
    target: orders
    type: rate_limit
    config:
      limit: 100
      window: 60s
      burst: 20

Step 4: Deploy & Test

Deploy with the command-line tool

The examples use the esbctl command-line tool.

# Validate config
./esbctl config validate config.yaml

# Log in as the bootstrap admin and store a bearer session.
# Username: the configured bootstrap admin (default `admin`).
# Password: the bootstrap admin password issued with your installation
# (in Compose, the ESB_BOOTSTRAP_ADMIN_PASSWORD secret).
./esbctl login --username admin

# Deploy config using the stored session
./esbctl config deploy config.yaml

esbctl login exchanges the bootstrap admin’s username and password for a bearer session that the CLI stores locally and renews automatically; every later esbctl command uses it. There is no static admin API key to pass: the bootstrap key is disabled once initialization completes, and admin API calls made with it return 401 Unauthorized.

--api-key (or the ESB_API_KEY environment variable) authenticates a service account, not an administrator. Use it only for headless automation against a service account created by your administrator, for example:

./esbctl --api-key <service-account-key> users list

Signing in when OIDC SSO is enabled

If your deployment has OIDC SSO enabled (enterprise.identity.enabled: true), the console login page offers a Sign in with your identity provider link alongside the username/password form. Clicking it runs the authorization-code

• PKCE flow against your IdP and lands you in the console with the same session a local login issues; esbctl login (local username/password) keeps working in parallel. Setting SSO up — registering the IdP client, the group_roles map, environment scoping — is covered in the OIDC SSO section of the Deployment guide that comes with your package.

Test via API

# Test route matching
./esbctl route test /api/orders \
  --service orders \
  --operation create \
  --payload test-order.json   # a JSON file holding a sample order

# Execute a flow (use the consumer API key issued for your consumer)
curl -X POST http://localhost:8080/api/v1/flows/order-processing \
  -H "Content-Type: application/json" \
  -H "X-Consumer-API-Key: $CONSUMER_API_KEY" \
  -d '{"product": "widget", "quantity": 5}'

# Check health
./esbctl health

Step 5: Monitor

1. Open Grafana at http://localhost:3000 and sign in with the credentials of your Grafana installation
2. View pre-loaded dashboards:
   • ESB Platform Health — nodes, memory, goroutines
   • ESB Service Health — error rates, circuit breakers
   • ESB Flow Health — executions, compensations, queue backlog

Next steps

• Connect a System — wire a remote system in as a connector route with secret references.

Troubleshooting