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

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 settings.env
nano settings.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))"

# 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

Step 5: Start WireBuddy¶

docker compose up -d

Check the logs:

docker compose 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

Step 7: Secure with Reverse Proxy (Recommended)¶

For production use, place WireBuddy behind a reverse proxy with HTTPS.

# Caddyfile (included in repository)
wirebuddy.example.com {
    reverse_proxy localhost:8000
}

server {
    listen 443 ssl http2;
    server_name wirebuddy.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# docker-compose.yml labels
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.wirebuddy.rule=Host(`wirebuddy.example.com`)"
  - "traefik.http.routers.wirebuddy.entrypoints=websecure"
  - "traefik.http.routers.wirebuddy.tls.certresolver=letsencrypt"

Next Steps¶

Now that WireBuddy is running:

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

Troubleshooting¶

# Check logs
docker compose logs wirebuddy

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

sudo netstat -tulpn | grep :8000

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

Updating WireBuddy¶

To update to the latest version:

cd wirebuddy
docker compose pull
docker compose up -d