Configuration reference

Everything BROKA reads at startup comes from the .env beside your compose.yml. There is no config file to mount and no settings screen that changes how the containers boot: what is in that file is what runs.

Required

None of these have defaults. A missing value stops the container at startup and names the variable — it does not fall back to something that would let the installation run on a publicly known key.

Variable	Read by	Notes
POSTGRES_PASSWORD	postgres, orchestrator, broker	The database is never published to the host; this password guards the Compose network only.
BROKA_JWT_SECRET	orchestrator	Signs access tokens. At least 32 bytes — the orchestrator refuses to start on anything shorter.
BROKA_KEK	orchestrator and broker	Encrypts stored broker credentials. Base64 of exactly 32 bytes (AES-256). Byte-identical in both services.
BROKA_KEK_ID	orchestrator and broker	The label of the active key, used by rotation. Not a secret; kek-1 is fine. Byte-identical in both.
BROKA_SERVICE_TOKEN	orchestrator and broker	Authorises the internal API between them. Byte-identical in both.

The three "byte-identical" values are the ones worth checking twice. A mismatch is not a startup error: it surfaces later as every broker screen failing with "Valid service credentials are required to call the internal contract.", or a stored credential that cannot be decrypted.

Images and version

Variable	What it does
BROKA_VERSION	The tag pulled for all three BROKA images; ships pinned to 1.0.0. Keep it pinned — an upgrade should be an edit you make, not something that happens on restart.
BROKER_IMAGE	The broker service's image; the Community repository by default.
ORCHESTRATOR_IMAGE	The API's image; the Community repository by default.
UI_IMAGE	The console's image; the Community repository by default.

Installing the Commercial images is described in the customer portal, for an organisation with a subscription.

Optional

Each has a working default in .env.example; change one only for the reason given.

Variable	Default	What it does
BROKA_DB_SSL_MODE	prefer	TLS from both services to PostgreSQL: prefer or require. The bundled PostgreSQL speaks plaintext on the private Compose network, so require only makes sense against an external PostgreSQL with TLS. Neither encrypts the database at rest.
BROKA_JWT_KEY_ID	jwt-1	A name for the token-signing key, written into every token.
BROKA_JWT_PREVIOUS_ID · BROKA_JWT_PREVIOUS	empty	The outgoing signing key, only while you rotate it: move the current pair here, put a new one above, restart, wait one access-token lifetime (15 minutes), then clear these. Nobody is signed out. One set without the other is refused at startup.
BROKA_KEK_PREVIOUS_ID · BROKA_KEK_PREVIOUS	empty	The outgoing key-encryption key, only while you rotate it — see the install page. One set without the other is refused at startup.
BROKA_LICENCE_SERVER	https://license.broka.dev	Where a Commercial installation activates and refreshes online. Community never calls it. Blank it to switch online activation off.
BROKA_TRUSTED_PROXIES	172.16.0.0/12	Which peers the console believes about the client's address and scheme. The default covers a TLS proxy on the same host; name a proxy on another machine, or none. Without it everyone behind your proxy shares one address — one sign-in rate limit, and the proxy's address in the audit trail.
BROKA_PUBLIC_URL	empty	The address people open the console at, for the link in an alert notification. Empty means notifications carry no link rather than a guessed one.
BROKA_KEYSTORE_DIR	/etc/broka/keystores	The only directory a Kafka connection may name a keystore file in, on the broker container. Nothing is mounted there by default; empty refuses file-based keystores outright.
BROKA_METRICS_PROMETHEUS	false	true serves the orchestrator's own metrics for a Prometheus you run, on port 9464 inside the Compose network — never published, and nothing is pushed anywhere. Off by default because it carries no login.

Networking

Variable	Default	What it does
BROKA_HTTP_PORT	3000	The host port the console is published on. It is the only port BROKA publishes.

Everything else talks over the Compose network by service name — the console reaches the API at orchestrator:8080, the API reaches the broker service at broker:8081, and both reach the database at postgres:5432. None of those are published to the host, and none of them are configurable from .env: they are the shape of the deployment, not a setting.

What happens when a value is missing

Situation	What you see
A required variable is absent from .env, or empty	Compose refuses to start the service and names the variable.
The image is run some other way with a required value empty	The container starts, checks, and exits 78 with FATAL: <VARIABLE> is not set. on stderr.
BROKA_JWT_SECRET is shorter than 32 bytes	The orchestrator refuses to start and says so.
BROKA_KEK does not decode to 32 bytes	The orchestrator refuses to start and says so.

That the images ship these variables blank rather than unset is deliberate. Blank is present- and-empty, which trips validation; unset would inherit whatever the image was built with, and an image that inherits its own development keys is an image that runs on publicly known secrets.

The broker service goes one step further: if it detects the development service token or the development key-encryption key in effect, it refuses to start unless the run is explicitly marked as development. It fails closed — every other case, including no profile at all, arms the check.

Not configurable, on purpose

• The database is included. PostgreSQL runs as one of the four containers on its own volume. There is no "point BROKA at your own PostgreSQL" variable in 1.0.0.
• One broker container serves every platform. A commercial installation does not run one container per platform; it runs one image with every platform's module linked into it.
• TLS is not in the box. The console listens on plain HTTP inside the network and is published on one port; terminating TLS is the job of whatever sits in front.
• No usage reporting. BROKA does not report what you do with it — no analytics, no metrics sent anywhere, nothing about your brokers, topics, queues or messages ever leaves your network.

Licence activation, and what it sends

Community needs no licence and makes no outbound calls at all.

A commercial installation is activated once, and you choose how:

• Online — you paste an activation code from the portal, and the console makes one HTTPS call to exchange it for a signed licence, then re-checks about once a day.
• Offline — the console produces a request you send to us, and you paste the licence we send back. An installation activated this way never calls out at all.

The online request carries exactly nine fields: the activation code, this installation's id and public key, the product, its version, the edition, the platforms present in the image, a nonce and a timestamp. It carries no broker addresses, no topic or queue names, no credentials, no user identities and no usage of any kind — and the whole request body is written into your own audit trail, so you can verify that rather than take our word for it.

The licence is verified locally, by signature. The network is how it is delivered, not what makes it valid: if our licence server is unreachable, nothing changes until the licence's own expiry.