First-Run Setup

A Broch server starts from a small, fixed boot floor: an encryption key, a database, the hostname it serves, and your identity provider. Once it’s running, the first admin signs in and completes the last two steps — license and the subscription agreement — in the app. This page describes that flow end to end.

The Boot Floor

Every deployment supplies these at startup, through your deploy artifact’s environment (the broch-deploy modules and your platform’s install guide wire them in):

Setting	Variable(s)	Notes
At-rest encryption root	BROCH_MASTER_KEY	Generated in your environment — by the Terraform modules at provision time, or by you (openssl rand -base64 48) on Docker Compose. See At-Rest Encryption.
Database connection	ConnectionStrings__DefaultConnection	PostgreSQL. See Database.
Wildcard hostname	API__WILDCARDHOSTNAME	The domain tunnels are served under (e.g. tunnels.company.com).
Identity provider	AUTHENTICATION__*, incl. AUTHENTICATION__ADMINROLES	Your OIDC provider, plus the role that grants admin. See Identity Providers.

The identity provider is part of the floor, not a later step. The first admin authenticates through it — there is no separate local-admin or anonymous setup path — and admin access is granted by role, so a deployment with no admin role configured has no one who can administer it. Always include at least one role in AUTHENTICATION__ADMINROLES that your first admin holds in the IdP.

AUTHENTICATION__PROVIDER=Auth0          # or AzureAd, EntraExternalId, Okta, or Oidc (any OIDC issuer)
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__DOMAIN=company.auth0.com
AUTHENTICATION__ADMINROLES=broch_admin

See Identity Providers for the provider-specific values and the Environment Variables Reference for the full list. An admin can change the IdP later from the admin UI — it persists to the database and overrides the boot values — but the initial provider and admin role come from the boot floor.

What Happens in the App

With the boot floor in place, the server starts and serves the login page. Everything that remains happens in the app, on the first admin’s first sign-in:

1. Sign in. Navigate to your wildcard hostname (e.g. https://tunnels.company.com) and log in through your IdP. A user holding a role in AUTHENTICATION__ADMINROLES lands in the first-run setup wizard.
2. Buy your license — or enter an existing key. The wizard leads with Buy Broch: choose your developer seats, accept the subscription agreement, and check out through Stripe. On return, Broch claims and activates your license automatically — there’s no key to paste. Already hold a license key (renewal or marketplace import)? Choose I already have a license key and paste it; Broch exchanges your key and wildcard hostname with the central server for a signed token and persists it to the database.
3. Accept the subscription agreement. Buying in-app accepts it before payment. If you entered an existing key and the license still requires acceptance, the wizard presents the agreement before completing.
4. Ready. The admin is dropped into the app. On every later restart the token loads from the database immediately — no re-entry, no further setup.

Completing licensing only after signing in binds activation to a real authenticated identity: it can only be done by someone your IdP has already authenticated as an admin.

Where This Fits

First-run setup happens after installation. Work through Before You Begin and your platform’s install guide first; this page picks up the moment the server is running and you open it in a browser.

Questions?

Contact Broch at [email protected].