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.

# Provider is one of: Auth0, AzureAd, EntraExternalId, Okta, Oidc (any OIDC issuer)
AUTHENTICATION__PROVIDER=Auth0
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__DOMAIN=company.auth0.com
# broch_admin is an example — replace with admin group(s)/role(s) from your
# own IdP. Comma-separated; holding any listed role grants admin.
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.

Register the IdP callback URL before that first sign-in. OIDC redirects back to https://<your-wildcard-hostname>/auth/callback — register that exact URL as an allowed callback / redirect URI in your IdP app, or you’ll reach the login page and get bounced. Do it when you create the IdP app (some providers, e.g. Okta and Entra, don’t let you edit it freely afterward). See Identity Providers for where that field lives in each provider.

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. Start your trial or buy — or enter an existing key. The wizard leads with Buy Broch: choose your developer seats, accept the subscription agreement, and check out through Stripe. New deployments start with a 15-day free trial — a valid card is required upfront but isn’t charged; billing begins on day 16 at $10 per seat / month unless you cancel first (manage or cancel anytime under Configuration → License). 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.

Trusted Proxy CIDRs (when your proxy isn’t on the same host)

Broch reads the real client IP from X-Forwarded-For, but only from proxies it trusts. A proxy on the same machine (loopback) is trusted automatically — no config. A proxy on a different host or container — the Caddy compose sidecar on the Docker bridge, or a cloud load balancer — must be listed under Share → Trusted Proxy CIDRs. Until it is, Broch can’t tell the client IP from the proxy’s, so Share policy rules that use Network (IP/CIDR) conditions fail closed — they deny — and audit logs record the proxy IP. Header-based and allow-all policies are unaffected. The Trusted Proxies card auto-detects your ingress IP and suggests a range. See Ingress.

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].