Skip to content

Environment Variables

WireBuddy can be configured via environment variables in settings.env (Docker) or .env (local development).

Required Variables

WIREBUDDY_SECRET_KEY

Required encryption key for secrets and session management.

WIREBUDDY_SECRET_KEY=your_generated_secret_key_here

Generate a secure key:

# Using OpenSSL
openssl rand -base64 32

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

Security Critical

  • Never commit this to version control
  • Use a different key for each environment
  • Regenerating this key will invalidate all sessions and encrypted data

Optional Variables

LOG_LEVEL

Logging verbosity level.

LOG_LEVEL=INFO

Options:

  • DEBUG - Verbose logging (development only)
  • INFO - Standard logging (recommended)
  • WARNING - Warnings and errors only
  • ERROR - Errors only
  • CRITICAL - Critical errors only

Default: INFO

PORT

Web server port.

PORT=8000

Default: 8000

Note

When using network_mode: host, the port must be available on the host.

HOST

Web server bind address.

HOST=0.0.0.0

Options:

  • 0.0.0.0 - Listen on all interfaces (default)
  • 127.0.0.1 - Localhost only
  • Specific IP - Bind to specific interface

Default: 0.0.0.0

UVICORN_WORKERS

Number of Uvicorn worker processes.

UVICORN_WORKERS=1

Default: 1

WireBuddy web mode is single-worker only. Values greater than 1 are not supported and are forced back to 1 by the Docker entrypoint.

SERVER_MODE

Deployment mode for multi-node architecture.

SERVER_MODE=master

Options:

  • master - Full application with web UI, database, and API (default)
  • node - Lightweight WireGuard-only mode for remote nodes

Default: master

Multi-Node Deployment

See Multi-Node Deployment for complete setup guide.

WIREBUDDY_ENROLLMENT_TOKEN

Node enrollment token (node mode only).

WIREBUDDY_ENROLLMENT_TOKEN=eyJub2RlX2lkIjoiYWJjZGVmIiwiZXhwIjoxNzQwMDAwMDAwfQ.a1b2c3d4...

Required when SERVER_MODE=node. Obtain this token from the master's Nodes page.

Single-Use Token

The token is invalidated after successful enrollment. Store securely.

WIREBUDDY_MASTER_URL

Master server API URL (node mode only).

WIREBUDDY_MASTER_URL=https://master.example.com

Legacy variable for node mode.

Current node enrollment tokens already include the master URL, so this variable is usually not needed.

Firewall Configuration

Ensure the node can reach the master's sync endpoints: /api/nodes/enroll, /api/nodes/heartbeat, /api/nodes/config, /api/nodes/events

WIREBUDDY_ENROLLMENT_VERIFY_KEY

Optional enrollment token HMAC verification key (node mode only).

WIREBUDDY_ENROLLMENT_VERIFY_KEY=your_hmac_verify_key

If set, the node verifies enrollment token signatures locally before contacting the master. In production, this is required by the node daemon.

WIREBUDDY_MASTER_CA_FILE

Path to a custom CA certificate file for master TLS verification (node mode only).

WIREBUDDY_MASTER_CA_FILE=/app/data/certs/master-ca.pem

If unset, system CA certificates are used.

WIREBUDDY_NODE_SYNC_INTERVAL

Normal sync interval in seconds (node mode only).

WIREBUDDY_NODE_SYNC_INTERVAL=30

Default: 30

WIREBUDDY_NODE_SYNC_INTERVAL_FAST

Fast sync interval in seconds used when SSE is disconnected (node mode only).

WIREBUDDY_NODE_SYNC_INTERVAL_FAST=5

Default: 5

WIREBUDDY_ENROLLMENT_RETRY_ATTEMPTS

Number of enrollment retry attempts on transient errors (node mode only).

WIREBUDDY_ENROLLMENT_RETRY_ATTEMPTS=3

Default: 3 (minimum effective value: 1)

WIREBUDDY_NO_FIREWALL_FIX

Disable automatic iptables DNS rule adjustments on node startup.

WIREBUDDY_NO_FIREWALL_FIX=1

Default: disabled (automatic firewall fix is enabled)

WIREBUDDY_SKIP_NETWORK_CHECK

Skip container network mode verification (CI/CD only).

WIREBUDDY_SKIP_NETWORK_CHECK=1

Default: Not set

Warning

Only use for testing. WireBuddy requires host network mode for full functionality.

DATABASE_PATH

Custom database location.

DATABASE_PATH=/custom/path/wirebuddy.db

Default: data/wirebuddy.db

DATA_DIR

Base data directory.

DATA_DIR=/custom/data

Default: data/

TSDB_PATH

Time-series database location.

TSDB_PATH=/custom/tsdb

Default: data/tsdb/

GEOIP_DATA_DIR

GeoLite2 database directory.

GEOIP_DATA_DIR=/custom/geoip

Default: data/geolite2/

DNS_LOG_PATH

Unbound DNS log file location.

DNS_LOG_PATH=/var/log/unbound/queries.log

Default: data/dns/queries.log

CERT_DIR

ACME certificate storage directory.

CERT_DIR=/custom/certs

Default: data/certs/

Advanced Variables

WIREBUDDY_STATUS_TRUSTED_PROXY_CIDRS

Comma-separated list of trusted proxy CIDRs for the /status endpoint.

WIREBUDDY_STATUS_TRUSTED_PROXY_CIDRS=127.0.0.1/32,192.168.1.10/32

Default: unset

Behavior:

  • Loopback proxy hops are trusted automatically
  • Other proxy hops are trusted only when listed here
  • Used for accepting X-Forwarded-For or X-Real-IP on /status

Custom session cookie name.

SESSION_COOKIE_NAME=wirebuddy_session

Default: wirebuddy_session

Require HTTPS for session cookies.

SESSION_COOKIE_SECURE=true

Default: false (auto-detect when behind reverse proxy)

Prevent JavaScript access to session cookies.

SESSION_COOKIE_HTTPONLY=true

Default: true (recommended)

SameSite cookie attribute.

SESSION_COOKIE_SAMESITE=Lax

Options:

  • Strict - Strictest (may break some workflows)
  • Lax - Balanced (recommended)
  • None - Least strict (requires SESSION_COOKIE_SECURE=true)

Default: Lax

RATELIMIT_ENABLED

Enable rate limiting.

RATELIMIT_ENABLED=true

Default: true

RATELIMIT_LOGIN_ATTEMPTS

Maximum login attempts before lockout.

RATELIMIT_LOGIN_ATTEMPTS=5

Default: 5

RATELIMIT_LOGIN_WINDOW

Login rate limit window (minutes).

RATELIMIT_LOGIN_WINDOW=15

Default: 15

SWAGGER_ENABLED

Enable Swagger/OpenAPI documentation endpoint.

SWAGGER_ENABLED=false

Default: true (can disable in production)

Access at: http://localhost:8000/swagger

CORS_ORIGINS

Allowed CORS origins (comma-separated).

CORS_ORIGINS=https://vpn.example.com,https://admin.example.com

Default: Not set (CORS disabled)

TZ

Timezone for scheduled tasks. Scheduled backups run at 03:00 in the resolved application timezone, using TZ when set and otherwise falling back to the system timezone configuration. Uses standard IANA timezone names.

TZ=America/New_York

See: List of tz database time zones

Default: Etc/UTC

Example Configuration Files

Production (settings.env)

# Required
WIREBUDDY_SECRET_KEY=<generated-secret-key>

# Application
LOG_LEVEL=INFO
PORT=8000
WORKERS=4

# Security
SESSION_COOKIE_SECURE=true
RATELIMIT_ENABLED=true
SWAGGER_ENABLED=false

# Optional
TZ=America/New_York

Development (.env)

# Required
WIREBUDDY_SECRET_KEY=dev-secret-key-change-me

# Application
LOG_LEVEL=DEBUG
PORT=8000
WORKERS=1

# Security (relaxed for dev)
SESSION_COOKIE_SECURE=false
RATELIMIT_ENABLED=false
SWAGGER_ENABLED=true

# Optional
DATA_DIR=./dev-data

Docker Compose

services:
  wirebuddy:
    image: giiibates/wirebuddy:latest
    env_file:
      - settings.env
    environment:
      - LOG_LEVEL=INFO
      - PORT=8000

Precedence

Environment variables follow this precedence (highest to lowest):

  1. Docker Compose environment section
  2. Docker Compose env_file
  3. Shell environment
  4. .env file
  5. Application defaults

Security Best Practices

Secret Management

Don't:

  • ❌ Commit secrets to Git
  • ❌ Use weak secrets (admin, password123)
  • ❌ Reuse secrets across environments
  • ❌ Share secrets in plain text (email, Slack)

Do:

  • ✅ Generate strong random secrets
  • ✅ Use different secrets per environment
  • ✅ Store secrets in secure vault (1Password, Bitwarden, Vault)
  • ✅ Rotate secrets periodically
  • ✅ Use .env.example for documentation (no real secrets)

File Permissions

Protect environment files:

# settings.env should be readable only by owner
chmod 600 settings.env

# Verify
ls -la settings.env
# -rw------- 1 user user 123 Mar 15 10:00 settings.env

Docker Secrets

For Docker Swarm, use Docker secrets:

services:
  wirebuddy:
    secrets:
      - wirebuddy_secret_key
    environment:
      - WIREBUDDY_SECRET_KEY_FILE=/run/secrets/wirebuddy_secret_key

secrets:
  wirebuddy_secret_key:
    external: true

Troubleshooting

Changes Not Applied

Problem: Environment variable changes not taking effect

Solutions:

  1. Restart container: 

    docker compose restart wirebuddy

  2. Verify variable is set: 

    docker compose exec wirebuddy env | grep WIREBUDDY

  3. Check for typos in variable names

Invalid Secret Key

Error: Failed to decrypt data

Cause: WIREBUDDY_SECRET_KEY changed or lost

Solutions:

  1. Restore correct secret key from backup
  2. Or reinitialize database (loses encrypted data): 
    docker compose down
rm data/wirebuddy.db
docker compose up -d

Port Already in Use

Error: Address already in use

Solutions:

  1. Change PORT to unused port
  2. Or stop conflicting service: 
    sudo lsof -i :8000
sudo kill <PID>

Next Steps