Docker Compose Installation

Deploy Broch on any Linux host with Docker. Works on any cloud VM, on-premises server, or bare metal — the most portable option.

Prerequisites

Complete these steps before proceeding:

• Docker Engine 24+ with Compose V2 installed
• Wildcard domain & DNS configured
• TLS certificate approach decided — Caddy automatic or bring your own
• Identity provider app registration created
• License key obtained

Step 1: Get the Files

Download the Docker Compose configuration and environment template:

curl -O https://raw.githubusercontent.com/broch-io/broch/main/deploy/docker-compose/docker-compose.yml
curl -O https://raw.githubusercontent.com/broch-io/broch/main/deploy/docker-compose/.env.template
cp .env.template .env

Step 2: Configure

Edit .env and set the required values:

# License key from Broch
BROCH_LICENSE=XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX

# Your wildcard hostname (e.g. tunnels.company.com)
API__WILDCARDHOSTNAME=tunnels.company.com

# Admin email address
Broch__AdminEmail=[email protected]

# Database password (embedded PostgreSQL)
POSTGRES_PASSWORD=a-strong-random-password

# Authentication provider (AzureAd, EntraExternalId, Auth0, or Okta)
AUTHENTICATION__PROVIDER=AzureAd
AUTHENTICATION__CLIENTID=<client-id>
AUTHENTICATION__CLIENTSECRET=<client-secret>
AUTHENTICATION__ADMINROLES=Admin

# Azure AD specific:
AUTHENTICATION__TENANTID=<tenant-id>

See Environment Variables for a complete reference.

Step 3: Configure TLS

Choose one approach.

Option A — Caddy (automatic, recommended)

Caddy obtains and renews the wildcard certificate automatically via ACME DNS-01. No manual certificate management.

Set these additional values in .env:

# DNS provider for automatic TLS (cloudflare or route53)
DNS_PROVIDER=cloudflare
DNS_API_TOKEN=your-dns-provider-api-token

Then start with the Caddy override:

docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

Option B — Bring your own certificate

Broch does not terminate TLS itself — it requires an ingress (reverse proxy) in front of it. The included docker-compose.yml ships with nginx for this purpose, but you can substitute Caddy in static-cert mode, Traefik, or any other reverse proxy that can terminate TLS and forward to broch-server:8080.

Place your wildcard certificate and private key in PEM format:

mkdir -p certs
cp /path/to/fullchain.pem certs/cert.pem
cp /path/to/privkey.pem certs/key.pem

The included nginx configuration mounts certs/ automatically and handles WebSocket proxying. If you bring your own ingress, ensure it forwards Upgrade and Connection headers for WebSocket support.

Step 4: Start

If you chose Option A (Caddy):

docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

If you chose Option B (BYO cert):

docker compose up -d

Step 5: Verify

Check server health:

curl https://tunnels.company.com/healthz        # liveness — 200 if running
curl https://tunnels.company.com/health/ready   # readiness — 200 after license + auth loads

The readiness endpoint returns 503 until the server has loaded its license token and authentication configuration. This typically takes 10–30 seconds on first boot (license activation call to Broch). On subsequent restarts the token is loaded from the database immediately.

Using an External Database

For managed databases (RDS, Azure Flexible Server, etc.), see Database, then start with the external DB override:

docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d

Firewall Requirements

Port	Required for
80	HTTP → HTTPS redirect
443	HTTPS API, tunnel proxy, WebSocket transport

Upgrading

# Set IMAGE_TAG in .env to the new version
docker compose pull
docker compose up -d

Database migrations run automatically on startup. Active tunnel connections drop on restart — CLI clients reconnect automatically.

Backup (Embedded PostgreSQL)

docker compose exec postgres pg_dump -U broch brochdb > backup-$(date +%Y%m%d).sql

Schedule this to run daily and store backups off-site. Before upgrading, take a backup so you can roll back if needed.

Capacity

From load testing on 0.5 vCPU / 1 GB RAM:

Users	Minimum vCPU	Minimum RAM
Up to 100	0.5	1 GB
100–300	1	2 GB
300+	2	4 GB

Troubleshooting

Health check returns 503

The server hasn’t loaded its license or auth configuration yet. Check logs:

docker compose logs server

Common causes: missing or invalid BROCH_LICENSE, incorrect auth provider settings, or the server can’t reach the Broch central server for license activation.

Tunnels won’t connect

Verify firewall allows inbound traffic on ports 80 and 443. Check that the wildcard DNS record resolves correctly.

Database connection fails

Verify POSTGRES_PASSWORD in .env matches between the postgres and server services.