Install it, configure it, run it
The full reference lives in the GitHub repository and stays versioned with the code. This page is a map to it.
Quick install
A Linux VPS with Docker, public ports 80/443, and a domain pointed at it.
# fetch the Compose file and start BurrowGate
mkdir burrowgate && cd burrowgate
curl -fsSLO https://raw.githubusercontent.com/Rabbit-Company/BurrowGate/main/docker-compose.yml
docker compose up -d
# read the generated dashboard password
docker compose exec burrowgate cat /app/data/bootstrap-admin-password.txt
# then open
https://SERVER_IP/_burrowgate/adminDocumentation index
Each guide covers one part of BurrowGate in depth and lives alongside the source code on GitHub.
Access Lists
Global users, Argon2id passwords, TOTP enrollment, and signed identity headers.
SSO
OIDC single sign-on setup, enforcement, and back-channel logout.
Network Policies
IP, CIDR, and country rules, default actions, and precedence order.
Route Policies
Per-path access modes, rate limits, header policies, and caching.
Managed Protection
Managed WAF rules, monitor/block modes, and versioned rule metadata.
Adding Challenges
How the challenge provider registry works, for building your own.
Challenge Pages
Customizing the HTML a visitor sees during a browser challenge.
Error Responses
Custom HTML or JSON responses for blocks, limits, and origin failures.
TLS
Let's Encrypt automation, uploaded certificates, and key encryption.
Streams
TCP/UDP proxying, TLS termination, and Compose port mapping.
Bandwidth
Client vs. upstream bandwidth counters and aggregation.
GeoIP
MaxMind database setup and the optional auto-updater profile.
OpenMetrics
Prometheus and OpenTelemetry Collector export reference.
Common environment variables
The most frequently changed settings. See .env.example on GitHub for the complete list.
| Variable | Default | Description |
|---|---|---|
BG_HOST |
0.0.0.0 |
Listener address |
BG_HTTP_PORT / BG_HTTPS_PORT |
80 / 443 |
Internal listener ports |
DATABASE_URL |
sqlite://./data/burrowgate.db |
Bun.SQL database URL - also accepts postgres:// and mysql:// |
BG_ADMIN_USERNAME |
admin |
Dashboard username |
BG_ADMIN_PASSWORD |
generated | Dashboard password |
BG_MASTER_KEY |
generated | Encrypts certificate and ACME private keys - back this up with your database |
BG_EVENT_RETENTION_DAYS |
7 |
Default monitoring retention for new sites and streams |
BG_GEOIP_ENABLED |
true |
Enable country-level GeoIP enrichment |
BG_OPENMETRICS_ENABLED |
false |
Expose /_burrowgate/metrics for Prometheus-compatible scraping |
BG_DEFAULT_POW_DIFFICULTY |
18 |
Default SHA-256 challenge difficulty |
BG_WEBSOCKET_ENABLED |
true |
Enable WebSocket proxying |
BG_ACME_EMAIL |
empty | Default ACME contact email for Let's Encrypt |
The full README covers everything
Sites, load balancing, TLS, sessions, monitoring, and current limitations - all in one place.