Install with Docker Compose

Compose is how BROKA is installed: four containers on one host, described by a file you keep under version control, with every secret in a .env beside it.

Before you start. This host needs network reachability to the brokers you intend to manage. Community needs nothing else: it makes no outbound calls of its own and needs no activation of any kind. This page installs Community. Commercial is installed from the customer portal, with its own guide; its licence is activated over one HTTPS call and refreshed daily — or, if you activate offline, it makes no outbound calls at all.

Requirements

Docker Engine	24.0 or newer, with the Compose plugin
Architecture	linux/amd64
CPU / memory	Size for concurrent operators, not for broker throughput. The compose file gives the broker service 4 GiB of memory; the other three containers use under 300 MiB between them at rest. Leave room for both. (CPU figure pending measurement)
Database	Included — PostgreSQL 17 runs as one of the four containers, on its own volume
Outbound access	Not required by Community

1 · Get the two files

compose.yml and .env.example come from the download page. Put them in a directory of their own — that directory is now your installation.

Every image is signed with BROKA's image-signing key. To check one before step 3 runs it, with cosign 3 or later:

cosign verify --key https://broka.dev/keys/cosign.pub orchestalabs/broka-broker:1.0.0

The same command checks broka-orchestrator and broka-ui. A failure means the image you would pull is not the one BROKA signed: do not run it.

Each image also carries its software bill of materials (CycloneDX), attested with the same key. To check that the bill of materials is BROKA's and belongs to that image:

cosign verify-attestation --key https://broka.dev/keys/cosign.pub --type cyclonedx orchestalabs/broka-broker:1.0.0 > /dev/null

The redirect keeps the bill of materials itself off your screen; leave it out to read it.

2 · Fill in .env first, not the compose file

cp .env.example .env

Four values have to be generated, once, at install time. The Compose file ships no defaults for them: while one is missing or empty, docker compose up refuses before any container is created and names the variable, rather than booting with a publicly known key.

Variable	What it is	Generate with
POSTGRES_PASSWORD	The database password, used by all three services	openssl rand -base64 24
BROKA_JWT_SECRET	Signs access tokens; must be at least 32 bytes	openssl rand -base64 48
BROKA_KEK	Encrypts every broker credential you save; must decode to exactly 32 bytes	openssl rand -base64 32
BROKA_SERVICE_TOKEN	Authorises the internal call from the API to the broker service	openssl rand -hex 32

BROKA_KEK_ID is a label for the active key, not a secret — kek-1 is fine. The last three values are read by both the orchestrator and the broker service and must be byte-identical in both; a single .env value feeds both spellings for exactly that reason.

Read this before regenerating anything.

BROKA_KEK is the key-encryption key. Every broker connection secret you save — SASL passwords, TLS key passphrases, Schema Registry credentials — is encrypted with it and stored that way in PostgreSQL.

If you replace it on an installation that already has connections, those secrets become permanently unrecoverable. There is no error at startup and no warning in the console: the failure surfaces later as connections that suddenly cannot authenticate, and no database backup helps, because the database is not what was lost.

Generate it once. Then back up this file as carefully as you back up the database, and keep the two together — one without the other is useless.

Rotating the key deliberately is supported, and it is not the same as overwriting this value. Put the new key in BROKA_KEK under a new BROKA_KEK_ID, move the old pair into BROKA_KEK_PREVIOUS and BROKA_KEK_PREVIOUS_ID so existing secrets stay readable, restart, and then run Rotate key-encryption key in Settings ▸ Security, which re-wraps every stored key onto the new one. Only after that may the previous key be removed.

Pin the version while you are in the file:

BROKA_VERSION=1.0.0

Tracking latest makes an upgrade something that happens to you. Pinning makes it an edit you make on purpose, and a rollback a one-line revert.

3 · Start the stack

docker compose up -d
docker compose logs -f orchestrator

The four containers start in a fixed order — PostgreSQL, then the orchestrator, then the broker service and the console — each waiting for the one before it to report healthy. The orchestrator applies its database migrations while it starts; when it answers its health check, they are done.

Open http://localhost:3000 and create the first administrator. That account is the only one that exists; every other account is created from inside, under Settings ▸ Users.

4 · Add an environment and a connection

1. Check your environments. A Development environment, open, already exists; add the others you need under Settings ▸ Environments. An environment is not a label — it carries the policy that later decides whether a write is accepted at all. A connection is created in the environment the top bar is showing.
2. Add a connection and pick the platform — Kafka, and in Commercial Redis, RabbitMQ, Apache Artemis or Memcached — from Settings ▸ Connections ▸ New connection. Each form asks only for what that platform needs.
3. Test it before saving. BROKA reports whether it reached the server and signed in, with the round-trip time, and says why when it could not. On Redis and RabbitMQ a passing test also carries a caveat when the credentials fall short of what the console needs — a Redis identity that may not run INFO, a RabbitMQ account that is not an administrator, or AMQP not accepting the connection.
4. Open the cluster. Topics, keys, queues, consumer groups — whatever that platform has — with the shared metadata layer of owners and labels on top — and, in Commercial, applications.

Commercial installations have one more step: Settings ▸ Licence, where you paste the activation code from the portal, or, if this host has no internet access, generate a request, send it to us and paste the licence we send back. Until it is activated, Kafka works fully and the commercial platforms are not offered at all: their pages appear once a licence names them.

If it does not come up

What you see	What it means
docker compose up stops before creating any container, saying a variable is required	That variable is missing or empty in .env. The Compose file fails closed on purpose.
The console loads but every broker call fails	The orchestrator and the broker service disagree about BROKA_SERVICE_TOKEN or BROKA_KEK. Both must be byte-identical.