How to Install WGDashboard - An Opensource Web UI for WireGuard VPN

WGDashboard is an open-source web interface that streamlines the management of WireGuard VPN servers. It provides a centralized dashboard where administrators can create interfaces, generate client configurations, monitor active peers, and manage VPN traffic from a single location.

This article shows how to deploy WGDashboard on Ubuntu 24.04 using Docker Compose with Traefik as a reverse proxy. Traefik automatically provisions HTTPS certificates through Let’s Encrypt, simplifying the setup and securing access to the dashboard. By the end of this guide, you deploy a fully containerized WGDashboard instance, configure WireGuard interfaces, and connect clients to your VPN server.

Prerequisites

Before you begin, you need to:

• Have access to an Ubuntu 24.04-based server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure a domain A record pointing to your server's IP address (for example, wgdashboard.example.com).

Set Up the Directory Structure and Environment Variables

In this section, you prepare the required directory structure for WGDashboard and define environment variables in a .env file.

1. Create the directory structure for WGDashboard.

   CONSOLE

   Copy

   $ mkdir -p ~/wgdashboard/{conf,data}

   Explain Code

   Powered by Vultr AgentBeta

   These directories store different types of data:

   • conf: Contains WireGuard configuration files from /etc/wireguard.
   • data: Stores WGDashboard application data, database, and settings.

2. Navigate into the wgdashboard directory.

   CONSOLE

   Copy

   $ cd ~/wgdashboard

   Explain Code

   Powered by Vultr AgentBeta

3. Create a .env file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following variables.

   INI

   Copy

   DOMAIN=wgdashboard.example.com
   LETSENCRYPT_EMAIL=admin@example.com

   Explain Code

   Powered by Vultr AgentBeta

   Replace:

   • wgdashboard.example.com with your domain.
   • admin@example.com with your email.

   Save and close the file.

Enable IP Forwarding on the Host

WireGuard requires IPv4 forwarding to route VPN client traffic to external networks. Enable forwarding on the host before deploying WGDashboard.

1. Enable IPv4 forwarding in the kernel configuration.

   CONSOLE

   Copy

   $ echo "net.ipv4.ip_forward=1" | sudo tee -a /usr/lib/sysctl.d/99-custom.conf

   Explain Code

   Powered by Vultr AgentBeta

2. Apply the sysctl changes without rebooting.

   CONSOLE

   Copy

   $ sudo sysctl --system

   Explain Code

   Powered by Vultr AgentBeta

Deploy WGDashboard with Docker Compose

In this section, you create and deploy the Docker Compose stack that runs WGDashboard behind Traefik. Docker Compose manages both containers, applies the environment variables from your .env file, and automatically configures HTTPS routing through Traefik.

1. Create a new Docker Compose manifest.

   CONSOLE

   Copy

   $ nano docker-compose.yaml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following content.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.6
       container_name: traefik
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - "letsencrypt:/letsencrypt"
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
       restart: unless-stopped
   
     wgdashboard:
       image: ghcr.io/wgdashboard/wgdashboard:latest
       container_name: wgdashboard
       hostname: wgdashboard
       expose:
         - "10086"
       ports:
         - "51820:51820/udp"
       volumes:
         - "./conf:/etc/wireguard"
         - "./data:/data"
       cap_add:
         - NET_ADMIN
       sysctls:
         - net.ipv4.ip_forward=1
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.wgdashboard.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.wgdashboard.entrypoints=websecure"
         - "traefik.http.routers.wgdashboard.tls.certresolver=letsencrypt"
         - "traefik.http.services.wgdashboard.loadbalancer.server.port=10086"
       restart: unless-stopped
   
   volumes:
     letsencrypt:

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   This manifest establishes:

   • services: Two containers deliver the VPN management platform:
     • traefik: Processes incoming connections, provisions TLS certificates, and routes traffic to WGDashboard.
     • wgdashboard: Runs the WireGuard management interface and VPN server.
   • image: WGDashboard image includes the complete runtime environment with WireGuard tools.
   • container_name: Consistent naming conventions streamline container management.
   • command (Traefik): Activates Docker integration, configures dual-port listeners (80/443), enforces protocol redirection, and enables Let's Encrypt certificate automation.
   • ports: Traefik exposes HTTP/HTTPS for the web interface. WGDashboard exposes UDP port 51820 for WireGuard VPN connections.
   • expose (WGDashboard): Opens port 10086 within the container network for Traefik access.
   • volumes: Bind mounts (./conf, ./data) preserve WireGuard configurations and application data across restarts. Named volume letsencrypt retains certificate data.
   • cap_add: Grants NET_ADMIN capability required for WireGuard to manage network interfaces inside the container.
   • sysctls: Enables IP forwarding within the container for VPN routing.
   • labels (WGDashboard): Traefik routing directives that enable proxying, specify hostname matching, attach SSL certificates, and define the backend port.
   • restart: unless-stopped: Implements automatic recovery after failures or system reboots.

3. Create and start the services.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that the services are running.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   Output:

   NAME           IMAGE                                    COMMAND                  SERVICE        CREATED          STATUS          PORTS
   traefik        traefik:v3.6                             "/entrypoint.sh --pr…"   traefik        30 seconds ago   Up 29 seconds   0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
   wgdashboard    ghcr.io/wgdashboard/wgdashboard:latest   "/bin/bash /entrypoi…"   wgdashboard    30 seconds ago   Up 29 seconds   0.0.0.0:51820->51820/udp, 10086/tcp

   Both containers are operational. WGDashboard manages WireGuard configurations while Traefik handles HTTPS connections on ports 80 and 443.

5. View the logs for the services.

   CONSOLE

   Copy

   $ docker compose logs

   Explain Code

   Powered by Vultr AgentBeta

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Access WGDashboard

In this section, you access the WGDashboard web interface and complete the initial administrator setup. Once logged in, you can manage WireGuard interfaces, create client peers, and monitor VPN activity from a centralized dashboard.

1. Open WGDashboard in your web browser.

   https://wgdashboard.example.com

   

2. Log in with the default credentials.

   • Username: admin
   • Password: admin

3. Create a new administrator account when prompted. Optionally configure multi-factor authentication (MFA) or click I don't need MFA to skip.

   

4. Navigate to Settings to configure WGDashboard options including peer defaults, DNS settings, and SMTP for email notifications.

   

Enable the Default WireGuard Client Configuration

By default, WGDashboard creates a WireGuard configuration (wg0) but does not automatically activate it. In this section, you enable the default configuration so the WireGuard interface becomes active and ready to accept client connections.

1. Navigate to the WireGuard Configurations section and click wg0 to open its settings.

   

2. Toggle the Status switch to enable the WireGuard configuration.

   

   After the WireGuard Configuration is enabled, the wg0 interface is created inside the docker container and begins listening on the configured UDP port.

Create a New WireGuard Configuration

In this section, you create a new WireGuard interface that operates independently from the default configuration. This approach allows you to separate clients, environments, or routing policies without modifying existing interfaces.

1. Navigate to Home and click + Configuration.

   

2. Configure the interface.

   

   Use the following example values:

   • Name: wg1
   • Listen Port: 51830
   • IP Address/CIDR: 10.1.0.1/24

3. Click Save to create the WireGuard interface.

Create Client Peers

In this section, you create client peers for the WireGuard interface and generate configuration files that clients use to connect to the VPN.

1. From the Home page, select the WireGuard interface you want to use (for example, wg0).

2. Click + Peer to add a new client.

   

3. Enter a client name (e.g., wgclient) and configure the allowed IPs. Use Advanced Options to customize DNS settings.

   

4. Click Add to create the peer.

5. Click the ... menu on the peer and select Download to export the client configuration file.

   

   The downloaded configuration file contains the keys, endpoint details, and routing information required to connect the client to the VPN

Connect Clients to the VPN

In this section, you import the generated WireGuard configuration into a client device and establish a secure VPN connection to the server.

1. Download the WireGuard client for your device (Windows, macOS, Linux, iOS, or Android).

2. Import the client configuration file downloaded from WGDashboard.

   

3. Click Activate to connect to the VPN.

   

4. Verify the VPN connection by checking your public IP address.

   CONSOLE

   Copy

   $ curl ifconfig.me/ip

   Explain Code

   Powered by Vultr AgentBeta

   The output should show your VPN server's public IP address.

5. Monitor active connections in WGDashboard by navigating to Clients or selecting Details for a specific peer.

   

Conclusion

You have successfully deployed WGDashboard using Docker Compose with Traefik as a reverse proxy and automatic SSL via Let's Encrypt. This containerized setup provides a web-based interface to manage WireGuard interfaces, create client configurations, and monitor VPN connections. For advanced features including API access and multi-server management, refer to the WGDashboard documentation.