giiibates/wirebuddy

By giiibates

Updated 25 days ago

Self-hosted WireGuard VPN with web UI, DNS ad-blocking, and real-time traffic analytics

Image
Networking
Security
0

6.3K

giiibates/wirebuddy repository overview


Use WireGuard with ease!

Docker Hub Docker Pulls Docker Image Size
License Platform Documentation

DocumentationQuick StartGitHub


A complete self-hosted VPN solution with web-based management, integrated Unbound DNS resolver, ad-blocking, real-time traffic analytics, and GeoIP visualization.

Features

CategoryHighlights
WireGuard VPNMulti-interface management, automatic keypair generation, routing presets, QR codes for mobile setup
DNS Ad-BlockingIntegrated Unbound resolver with blocklists, DNS-over-TLS, real-time query log, DNSSEC, client-scoped rules
MonitoringBuilt-in time-series database, per-peer traffic charts, traffic analysis by country & ASN
GeoIPMaxMind GeoLite2 integration, interactive heatmap, country flags & ASN badges
Let's EncryptBuilt-in ACME client with HTTP-01 challenge, certificate management UI
User ManagementMulti-user roles, Passkeys (WebAuthn) & MFA (TOTP), login tracking
Web UIResponsive Bootstrap 5, dark/light/auto theme, Material Icons

Quick Start

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.


Docker Compose

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

Environment Variables

VariableRequiredDefaultDescription
WIREBUDDY_SECRET_KEYYesEncryption key for database secrets. Generate with: head -c 32 /dev/urandom | base64
WIREBUDDY_BOOTSTRAP_ADMIN_PASSWORDRequired on first boot of a new DBInitial password for the bootstrap admin user when the database is created
LOG_LEVELNoINFOLog verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL
WIREBUDDY_PORTNo8000HTTP port for the web UI
WIREBUDDY_TRUST_PROXY_HEADERSNo1 in Docker entrypointTrust X-Forwarded-* headers from FORWARDED_ALLOW_IPS so CSRF and origin checks work behind HTTPS reverse proxies
FORWARDED_ALLOW_IPSNo127.0.0.1Comma-separated proxy IPs or CIDRs whose forwarded headers may be trusted
TZNoContainer defaultTime zone used for logs and scheduled tasks
WIREBUDDY_DATA_DIRNo/app/dataBase directory for persistent application data inside the container
WIREBUDDY_STATUS_TRUSTED_PROXY_CIDRSNoComma-separated CIDRs for trusted reverse proxies

Important: Keep WIREBUDDY_SECRET_KEY secure and consistent across container recreations. Losing this key means losing access to encrypted WireGuard private keys.


Volumes

PathDescription
/app/dataPersistent data (SQLite database, certificates, DNS configs, TSDB)

Requirements

  • Host network mode (--network host) — Required for WireGuard to manage network interfaces
  • NET_ADMIN capability — Required for creating WireGuard interfaces
  • TUN device (/dev/net/tun) — Required for VPN tunnels
  • Linux host with kernel 5.6+ (WireGuard built-in) or wireguard-dkms installed

Documentation

For complete installation guides, configuration options, API reference, and troubleshooting:

gill-bates.github.io/wirebuddy


License

GNU Affero General Public License v3.0 — see LICENSE for details.


Maintained by Gill-Bates

Tag summary

Content type

Image

Digest

sha256:6b2847b82

Size

119 MB

Last updated

25 days ago

docker pull giiibates/wirebuddy