Self-Host Your Blackhole Coordination Server in 15 Minutes

Blackhole's coordination server is fully open-source. You can run it on any VPS or private server. All your mesh metadata stays on your infrastructure. This guide gets you running with Docker Compose in about 15 minutes.

Step 1: Pull the Docker Compose file

Blackhole publishes official images to GitHub Container Registry. The Compose file includes the coordination server, PostgreSQL database, and an embedded STUN server for NAT traversal.

mkdir blackhole-server && cd blackhole-server
curl -fsSL https://blackhole.dev/docker-compose.yml -o docker-compose.yml
curl -fsSL https://blackhole.dev/env.example -o .env

Step 2: Configure environment variables

Edit the .env file with your domain and a random secret key. The coordination server uses this key to sign device tokens.

# Required
BH_DOMAIN=mesh.yourcompany.com
BH_SECRET_KEY=your-random-64-char-secret-here

# Database (managed for you by Docker Compose)
POSTGRES_PASSWORD=choose-a-strong-password

# Optional: SMTP for invite emails
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=postmaster@yourcompany.com
SMTP_PASS=your-smtp-password

# Optional: Disable telemetry (anonymous usage stats)
BH_TELEMETRY=false

Step 3: Start the server

The Compose file includes a Caddy reverse proxy that handles TLS certificate provisioning automatically via Let's Encrypt. Just bring it up:

docker compose up -d

Watch the logs to confirm everything started:

docker compose logs -f coordination
# blackhole-coord  | server ready on :443
# blackhole-coord  | STUN server listening on :3478
# blackhole-coord  | database migrations complete

Step 4: Create the first admin account

docker compose exec coordination bh-admin create-user \
  --email admin@yourcompany.com \
  --role admin

This prints a one-time setup link. Open it in a browser to set your password.

Step 5: Point your clients at the server

When running bh up on client devices, pass your server URL:

bh up --login-server https://mesh.yourcompany.com

To make this the default so users don't have to pass the flag every time, distribute a bh.conf file:

[server]
login_server = "https://mesh.yourcompany.com"

Keeping it updated

Pull the latest image and restart with zero-downtime rolling update:

docker compose pull
docker compose up -d --no-deps coordination