Self-hosted WireGuard VPN with web UI, DNS ad-blocking, and real-time traffic analytics
6.3K
Use WireGuard with ease!
Documentation • Quick Start • GitHub
A complete self-hosted VPN solution with web-based management, integrated Unbound DNS resolver, ad-blocking, real-time traffic analytics, and GeoIP visualization.
| Category | Highlights |
|---|---|
| WireGuard VPN | Multi-interface management, automatic keypair generation, routing presets, QR codes for mobile setup |
| DNS Ad-Blocking | Integrated Unbound resolver with blocklists, DNS-over-TLS, real-time query log, DNSSEC, client-scoped rules |
| Monitoring | Built-in time-series database, per-peer traffic charts, traffic analysis by country & ASN |
| GeoIP | MaxMind GeoLite2 integration, interactive heatmap, country flags & ASN badges |
| Let's Encrypt | Built-in ACME client with HTTP-01 challenge, certificate management UI |
| User Management | Multi-user roles, Passkeys (WebAuthn) & MFA (TOTP), login tracking |
| Web UI | Responsive Bootstrap 5, dark/light/auto theme, Material Icons |
docker run -d \
--name wirebuddy \
--network host \
--cap-drop ALL \
--cap-add NET_ADMIN \
--security-opt no-new-privileges:true \
--stop-timeout 20 \
--device /dev/net/tun:/dev/net/tun \
-e TZ=Etc/UTC \
-e WIREBUDDY_SECRET_KEY="$(head -c 32 /dev/urandom | base64)" \
-e WIREBUDDY_TRUST_PROXY_HEADERS=1 \
-v wirebuddy-data:/app/data \
giiibates/wirebuddy:latest
Then open http://<your-server-ip>:8000 in your browser.
If you run WireBuddy behind Caddy, nginx, or another reverse proxy on the same
host, leave WIREBUDDY_TRUST_PROXY_HEADERS=1 enabled so HTTPS origin checks use
the forwarded scheme correctly. If the proxy connects from a different IP or
container network, also set FORWARDED_ALLOW_IPS to that proxy IP or CIDR.
On first boot of a new database, set WIREBUDDY_BOOTSTRAP_ADMIN_PASSWORD so WireBuddy can create the bootstrap admin user safely.
services:
wirebuddy:
image: giiibates/wirebuddy:latest
container_name: wirebuddy
restart: always
stop_grace_period: 20s
network_mode: host
cap_drop:
- ALL
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
LOG_LEVEL: INFO
TZ: Etc/UTC
WIREBUDDY_SECRET_KEY: "" # Generate with: head -c 32 /dev/urandom | base64
# Required on first boot of a new database to create the bootstrap admin user
WIREBUDDY_BOOTSTRAP_ADMIN_PASSWORD: "change-me-now"
WIREBUDDY_TRUST_PROXY_HEADERS: "1"
# If your reverse proxy is not on 127.0.0.1, set its IP or CIDR here.
# FORWARDED_ALLOW_IPS: "127.0.0.1,172.18.0.0/16"
WIREBUDDY_DATA_DIR: /app/data
volumes:
- ./data:/app/data
logging:
driver: json-file
options:
max-size: "50m"
max-file: "5"
security_opt:
- no-new-privileges:true
healthcheck:
test: ["CMD", "curl", "--fail", "--silent", "--max-time", "5", "http://127.0.0.1:${WIREBUDDY_PORT:-8000}/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 15s
| Variable | Required | Default | Description |
|---|---|---|---|
WIREBUDDY_SECRET_KEY | Yes | — | Encryption key for database secrets. Generate with: head -c 32 /dev/urandom | base64 |
WIREBUDDY_BOOTSTRAP_ADMIN_PASSWORD | Required on first boot of a new DB | — | Initial password for the bootstrap admin user when the database is created |
LOG_LEVEL | No | INFO | Log verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL |
WIREBUDDY_PORT | No | 8000 | HTTP port for the web UI |
WIREBUDDY_TRUST_PROXY_HEADERS | No | 1 in Docker entrypoint | Trust X-Forwarded-* headers from FORWARDED_ALLOW_IPS so CSRF and origin checks work behind HTTPS reverse proxies |
FORWARDED_ALLOW_IPS | No | 127.0.0.1 | Comma-separated proxy IPs or CIDRs whose forwarded headers may be trusted |
TZ | No | Container default | Time zone used for logs and scheduled tasks |
WIREBUDDY_DATA_DIR | No | /app/data | Base directory for persistent application data inside the container |
WIREBUDDY_STATUS_TRUSTED_PROXY_CIDRS | No | — | Comma-separated CIDRs for trusted reverse proxies |
Important: Keep
WIREBUDDY_SECRET_KEYsecure and consistent across container recreations. Losing this key means losing access to encrypted WireGuard private keys.
| Path | Description |
|---|---|
/app/data | Persistent data (SQLite database, certificates, DNS configs, TSDB) |
--network host) — Required for WireGuard to manage network interfaces/dev/net/tun) — Required for VPN tunnelsFor complete installation guides, configuration options, API reference, and troubleshooting:
gill-bates.github.io/wirebuddy
GNU Affero General Public License v3.0 — see LICENSE for details.
Maintained by Gill-Bates
Content type
Image
Digest
sha256:6b2847b82…
Size
119 MB
Last updated
25 days ago
docker pull giiibates/wirebuddy