Quick Start Guide¶

Get WireBuddy running in under 5 minutes with Docker.

Prerequisites¶

Before you begin, ensure you have:

Docker Engine 20.10+ and Docker Compose
Linux host (amd64 or arm64)
Root or sudo access for sysctl configuration

Windows & macOS Users

WireBuddy requires network_mode: host which is only fully supported on Linux. For Windows/macOS, consider running it in a Linux VM.

Step 1: Clone the Repository¶

git clone https://github.com/Gill-Bates/wirebuddy.git
cd wirebuddy

Step 2: Configure Settings¶

Copy the example environment file and edit it:

cp .env-example .env
nano .env  # or use your preferred editor

Required: Set a secure WIREBUDDY_SECRET_KEY:

# Generate a secure key (Linux/macOS)
openssl rand -base64 32

# Or use Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Example .env

# Required: Encryption key for secrets & sessions
WIREBUDDY_SECRET_KEY=your-generated-secret-key-here

# Optional: Logging level
LOG_LEVEL=INFO

# Optional: Skip network mode check (CI/CD only)
# WIREBUDDY_SKIP_NETWORK_CHECK=1

Step 3: Enable IP Forwarding¶

WireGuard requires IP forwarding on the host:

sudo sysctl -w net.ipv4.conf.all.forwarding=1
sudo sysctl -w net.ipv6.conf.all.forwarding=1

# Make persistent across reboots
cat <<EOF | sudo tee /etc/sysctl.d/99-wireguard.conf
net.ipv4.conf.all.forwarding = 1
net.ipv6.conf.all.forwarding = 1
EOF

Step 4: Enable Conntrack Accounting (Optional but Recommended)¶

For traffic analysis by country and ASN, enable conntrack byte accounting:

sudo sysctl -w net.netfilter.nf_conntrack_acct=1

# Make persistent
echo "net.netfilter.nf_conntrack_acct = 1" | sudo tee -a /etc/sysctl.d/99-wireguard.conf

Verify it's enabled:

cat /proc/sys/net/netfilter/nf_conntrack_acct
# Should output: 1

Without Conntrack Accounting

Country and ASN traffic charts will show no data. WireBuddy will log a warning but continue to function.

Step 5: Start WireBuddy¶

docker compose --env-file .env -f docker/docker-compose.yml up -d

Check the logs:

docker compose --env-file .env -f docker/docker-compose.yml logs -f wirebuddy

Step 6: Access the Web Interface¶

Open your browser and navigate to:

http://localhost:8000

Or access from your network using the server's IP address:

http://YOUR_SERVER_IP:8000

Bootstrap Credentials

Username: admin
Password: printed once to the console at first startup (not logged, not stored). Read it with docker logs wirebuddy

WireBuddy will redirect you to a password change screen on first login. Set a secure password to continue.

Step 7: Secure with Reverse Proxy (Recommended)¶

For production use, place WireBuddy behind a reverse proxy with HTTPS. Ready-to-use Caddy, Nginx and Traefik configurations, including the unbuffered event-stream routes multi-node deployments need, are in the Installation Guide.

Next Steps¶

Now that WireBuddy is running:

First Steps - Configure your first WireGuard interface
WireGuard Management - Learn about peer management
DNS Ad-Blocking - Set up DNS filtering
User Management - Add additional users and enable MFA

Troubleshooting¶

Common Issues

Container won't start:

# Check logs
docker compose --env-file .env -f docker/docker-compose.yml logs wirebuddy

# Verify network mode
docker inspect wirebuddy | grep NetworkMode
# Should show: "host"

Can't access web interface: - Verify port 8000 is not blocked by firewall - Check if another service is using port 8000:

sudo netstat -tulpn | grep :8000

Traffic charts show no data: - Verify conntrack accounting is enabled (see Step 4) - Check WireBuddy logs for warnings

For more help, see the Troubleshooting page or open an issue.

Updating WireBuddy¶

To update to the latest version:

cd wirebuddy
docker compose --env-file .env -f docker/docker-compose.yml pull
docker compose --env-file .env -f docker/docker-compose.yml up -d

Data Persistence

Your configuration and data are stored in docker/data/ and persist across updates.