j4v3l/wireguard-dashboard repository overview

⁠Wireguard with Dashboard Docker Image

A Docker image running Wireguard VPN server with WGDashboard web interface on Alpine Linux. This container allows you to easily set up and manage a Wireguard VPN server with a web-based administration interface.

⁠Features

• Multi-architecture support: Run on any platform - amd64, arm64, armv7, and armhf
• Lightweight: Based on Alpine Linux for minimal resource usage
• WGDashboard integration: Web-based interface for easy Wireguard management
• Customizable configuration: Extensive environment variables for easy configuration
• Persistent storage: Volume mounts for configuration and client data
• Auto-generated configs: Automatic generation of initial Wireguard configuration if none exists
• Secure by default: Proper permissions and secure defaults
• Automatic updates: Optional automatic updates for Wireguard and WGDashboard
• Regular updates: Multiple release channels (stable, beta, latest)

⁠Supported Tags

• latest - Auto-applied on pushes to main
• stable - Published on version tags (also applied on main builds for convenience)
• beta - Auto-applied on pushes to dev
• vX.Y.Z and X.Y.Z - Versioned releases (semantic versioning)
• Multi-arch support: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6

⁠Quick Start

⁠Option 1: Using Docker

# Pull the image
docker pull j4v3l/wireguard-dashboard:latest

# Create directories for persistent storage
mkdir -p config dashboard-data

# Run the container
docker run -d \
  --name wireguard \
  --cap-add NET_ADMIN \
  --cap-add SYS_MODULE \
  --sysctl net.ipv4.ip_forward=1 \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  -p 51820:51820/udp \
  -p 10086:10086/tcp \
  -v "$(pwd)/config:/etc/wireguard" \
  -v "$(pwd)/dashboard-data:/opt/WGDashboard/src/db" \
  --restart unless-stopped \
  j4v3l/wireguard-dashboard:latest

⁠Option 2: Using Docker Compose (Recommended)

1. Create a docker-compose.yml file:

services:
  wireguard:
    image: j4v3l/wireguard-dashboard:beta
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - TZ=${TZ:-UTC}
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - WG_HOST=${WG_HOST:-auto}  # Server's public IP, 'auto' for automatic detection
      - WG_PORT=${WG_PORT:-51820}  # WireGuard port
      - WG_DASHBOARD_PORT=${WG_DASHBOARD_PORT:-10086}  # WGDashboard web interface port
      - WG_DASHBOARD_HOST=${WG_DASHBOARD_HOST:-0.0.0.0}  # WGDashboard bind address
      - WG_ALLOWED_IPS=${WG_ALLOWED_IPS:-0.0.0.0/0, ::/0}  # Allowed IPs for clients
      - WG_PERSISTENT_KEEPALIVE=${WG_PERSISTENT_KEEPALIVE:-25}  # KeepAlive interval
      - WG_DNS_SERVERS=${WG_DNS_SERVERS:-1.1.1.1,8.8.8.8}  # DNS servers for clients
      - AUTO_UPDATE=${AUTO_UPDATE:-false}  # Enable automatic updates of packages
      - UPDATE_DASHBOARD=${UPDATE_DASHBOARD:-false}  # Enable automatic updates of WGDashboard
    volumes:
      - ./config:/etc/wireguard
      - ./dashboard-data:/opt/WGDashboard/src/db
    ports:
      - "${WG_PORT:-51820}:51820/udp"
      - "${WG_DASHBOARD_PORT:-10086}:10086/tcp"
    restart: unless-stopped
    privileged: true  # Required for wireguard kernel module and network changes
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv6.conf.all.forwarding=1 
    # Optional: pin the embedded WGDashboard version (tag/branch/commit)
    build:
      context: .
      dockerfile: Dockerfile
      args:
        WGDASHBOARD_REF: master

1. Start the container:

docker-compose up -d

⁠Accessing the Dashboard

Once the container is running, access the WGDashboard at:

http://your-server-ip:10086

Default login credentials:

• Username: admin
• Password: admin

IMPORTANT: For security reasons, immediately change the default password after the first login.

⁠Environment Variables

⁠Automatic Updates

The container includes support for automatic updates of both Wireguard tools and the WGDashboard:

• Set AUTO_UPDATE=true to enable automatic updates of Wireguard tools when the container starts
• Set UPDATE_DASHBOARD=true to also update the WGDashboard from the Git repository when the container starts

Example with automatic updates enabled:

docker run -d \
  --name wireguard \
  --cap-add NET_ADMIN \
  --cap-add SYS_MODULE \
  -e AUTO_UPDATE=true \
  -e UPDATE_DASHBOARD=true \
  -p 51820:51820/udp \
  -p 10086:10086/tcp \
  -v "$(pwd)/config:/etc/wireguard" \
  -v "$(pwd)/dashboard-data:/opt/WGDashboard/src/db" \
  --restart unless-stopped \
  j4v3l/wireguard-dashboard:latest

⁠Volume Mounts

For data persistence, mount these volumes:

⁠Network Configuration

The container requires the following ports to be exposed:

⁠Security Considerations

1. Change default credentials: Immediately change the default admin password in WGDashboard
2. Firewall rules: Only expose necessary ports to the internet
3. Regular updates: Keep the container updated to receive security fixes
4. Key storage: Protect the /etc/wireguard directory as it contains private keys
5. Secure dashboard access: Consider putting the web interface behind a reverse proxy with HTTPS

⁠Adding Clients

WGDashboard provides an easy web interface for managing clients:

1. Navigate to http://your-server-ip:10086
2. Log in with your credentials
3. Select your Wireguard interface (default: wg0)
4. Click "Add Client" to create a new VPN client
5. Configure the client name and allowed IPs
6. The dashboard will generate configuration and QR codes for easy client setup

⁠Advanced Usage

⁠Custom Wireguard Configuration

You can provide your own wg0.conf file by placing it in the mounted /etc/wireguard directory before starting the container. If a configuration already exists, the container will use it instead of generating a new one.

⁠Running Behind NAT

If your server is behind NAT, you'll need to forward the appropriate ports:

• UDP port 51820 (or your custom WG_PORT) for Wireguard VPN
• TCP port 10086 (or your custom WG_DASHBOARD_PORT) for WGDashboard web interface

⁠Integration with Other Services

The container can be integrated with other services like Nginx Proxy Manager or Traefik for handling SSL termination and access control to the dashboard.

⁠Troubleshooting

⁠Common Issues

1. Container fails to start: Check if the required kernel modules are available on the host

   lsmod | grep wireguard
   

   Copy

2. Cannot connect to the VPN: Verify port forwarding and firewall rules

3. WGDashboard is not accessible: Check that the dashboard port is correctly exposed

4. Permission issues: Ensure proper PUID/PGID settings in the environment variables

5. No internet access through VPN: Several things to check:

   • Make sure the container is running in privileged mode or with --cap-add NET_ADMIN

   • Try using network_mode: host in your docker-compose.yml

   • Verify IP forwarding is enabled on the host: sysctl net.ipv4.ip_forward

   • Check iptables NAT rules: iptables -t nat -L -v

   • Ensure the client configuration has AllowedIPs = 0.0.0.0/0, ::/0 to route all traffic

   • For manual fix, run these commands on the host:

     sudo iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE
     sudo iptables -A FORWARD -i wg0 -j ACCEPT
     sudo iptables -A FORWARD -o wg0 -j ACCEPT
     

     Copy

⁠Logs

To view container logs:

docker logs wireguard
# or with docker-compose
docker-compose logs wireguard

⁠Healthcheck

This image includes a Docker healthcheck that probes the WGDashboard on port 10086. In Docker Compose, you can see the health status with:

docker ps --format '{{.Names}}\t{{.Status}}'

⁠Updates and Maintenance

⁠Updating the Container

# With Docker
docker pull j4v3l/wireguard-dashboard:latest
docker-compose down
docker-compose up -d

# With Docker Compose
docker-compose pull
docker-compose up -d

⁠Release and Tagging

• Push a git tag like v1.2.3 to trigger a multi-arch build and publish versioned images:
  • Docker Hub: j4v3l/wireguard-dashboard:v1.2.3, plus stable
  • GHCR: ghcr.io/j4v3l/wireguard-dashboard:v1.2.3, plus stable
• Merges to main publish latest (and stable as an alias), merges to dev publish beta.
• To pin a specific WGDashboard version baked into the image, build with:

docker build --build-arg WGDASHBOARD_REF=v4.2.3 -t j4v3l/wireguard-dashboard:v4.2.3 .

⁠Backup

To backup your Wireguard configuration and WGDashboard data:

# Stop the container first
docker-compose down

# Backup directories
tar -czvf wireguard-backup.tar.gz config/ dashboard-data/

# Restart the container
docker-compose up -d

⁠Technical Details

This Docker image includes:

• Alpine Linux (latest)
• Wireguard-tools
• WGDashboard (from https://github.com/donaldzou/WGDashboard⁠)
• Python 3 and dependencies
• iptables for network configuration

⁠Resources

• GitHub Repository⁠
• Docker Hub⁠
• Wireguard Official Website⁠
• WGDashboard Project⁠

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Contributing

Contributions are welcome! Please see CONTRIBUTING.md⁠ for details on how to contribute to this project.