Operations

This page is for anyone running a Brio-IO server. It is deliberately lean: it describes the knobs that exist today.

On availability: Brio-IO is in Early Access. There is no public self-service download; access and installation packages are set up personally. Ask us for access — tell us briefly which interfaces you want to integrate.

What a deployment consists of

A Brio-IO deployment has three parts:

• Brio-IO Server — the headless application. It holds the channels, the connectors and the runtime.
• PostgreSQL — the message store. The server runs schema migrations itself on startup.
• Brio-IO UI — the web interface. It is a separate deployment and is not bundled into the server: one UI can serve several servers (server selector in the interface) — production, staging and test in one console.

Configuration: profiles and environment variables

The server uses Spring profiles. Shipped profiles include brio-dev (default) and brio-staging; they differ in their defaults for database, configuration path and log level. Everything operationally relevant can be set through environment variables.

Database

Variable	Meaning
BRIO_DATASOURCE_URL	JDBC URL of the PostgreSQL instance
BRIO_DATASOURCE_USERNAME	database user
BRIO_DATASOURCE_PASSWORD	database password

Configuration repository

Variable	Meaning
BRIO_CONFIG_REPO_PATH	directory of the Git configuration repository

The default is ./data/config-repo (development) or /var/lib/brio/config-repo (staging profile). This directory is the configuration — channels, connectors, scripts, code templates. It belongs in your backup, and as a Git repository, not as a file copy.

Authentication and tokens

Variable	Meaning
BRIO_AUTH_MODE	local, oidc or both (default: local)
BRIO_ADMIN_USERNAME	name of the initial administrator (default: admin)
BRIO_ADMIN_PASSWORD	password of the initial administrator
BRIO_JWT_ACCESS_TTL	access token lifetime (default: 15 minutes)
BRIO_JWT_REFRESH_TTL	refresh token lifetime (default: 8 hours)

The token defaults are chosen deliberately: a short-lived access token the UI renews on its own, and a refresh token that covers one shift — so nobody has to re-authenticate in the middle of their work.

For OIDC (BRIO_AUTH_MODE=oidc or both) the usual knobs exist: BRIO_OIDC_ISSUER_URI, BRIO_OIDC_CLIENT_ID, BRIO_OIDC_CLIENT_SECRET, BRIO_OIDC_AUDIENCE, and BRIO_OIDC_ROLE_CLAIM for the path to the roles in the token (Keycloak stores them under realm_access.roles, Azure AD in a top-level roles claim). both keeps local login as a fallback — useful while the identity provider has not yet been proven as the sole way in.

Branch engine

Variable	Meaning
BRIO_BRANCH_ENGINE_ENABLED	branch engine on/off (default: on)
BRIO_BRANCH_ENGINE_MAX	maximum number of concurrent shadow engines (default: 5)
BRIO_BRANCH_ENGINE_MAX_MESSAGES	cap on stored shadow messages (default: 100,000)
BRIO_BRANCH_ENGINE_PURGE_ON_MERGE	clear shadow data on merge (default: on)
BRIO_BRANCH_ENGINE_PURGE_ON_DELETE	clear shadow data when a branch is deleted (default: on)
BRIO_BRANCH_ENGINE_MAX_DIFF_EXAMPLES	number of concrete divergence examples in the merge summary (default: 20; 0 = counts only)

Those two caps are why shadowing does not slowly fill the server up: shadow traffic is diagnostic material with a limited shelf life, not a second production data set.

Licence

Variable	Meaning
BRIO_LICENSE_KEY	licence key of the deployment
BRIO_LICENSE_SECRET	signing secret for licence verification

BRIO_LICENSE_SECRET must be set in production. The built-in default is explicitly for development only.

Health and info

The server exposes actuator endpoints:

curl -s http://localhost:8080/actuator/health

• health reports status; details are shown only to authorised callers.
• info carries build and Git details — useful to check which build is actually running. That exact question is the most common source of wrong diagnoses after a deploy.

The JMS health indicator is deliberately disabled: JMS connectivity is a per-channel concern in Brio-IO, not a process liveness signal. Without that opt-out, a missing broker would report the whole server as DOWN.

API documentation

The REST API is spec-first: the authoritative OpenAPI description is a maintained document the server serves at /api/docs. A Swagger interface sits at /swagger-ui.html and loads exactly that spec.

A full API reference is not part of this documentation — the spec on the server is the more current source.

Logging

Log levels per environment: DEBUG for io.brio in the development profile, INFO in the staging profile. When a channel is deployed, the log is worth a look — two warnings appear there that should be taken seriously:

• a deprecation warning when the channel contains at least one js-legacy script, naming the affected scripts;
• a warning about retired data-type paths in scripts (XPN_1, FN_1, …) that would silently return an empty string today. See Concepts.

Backups

Two things need backing up, and they are of different kinds:

1. The configuration repository (BRIO_CONFIG_REPO_PATH) — the truth about your channels. Best as a Git remote, so the backup is the history at the same time.
2. The PostgreSQL database — the message store.

A server can be rebuilt from the configuration repository alone; the database carries the processed messages, not the configuration.