How To Install WGDashboard on Debian 13

Managing WireGuard VPN configurations through command-line interfaces can become tedious and error-prone, especially when handling multiple peers and tunnels. WGDashboard transforms this experience by providing an intuitive web-based interface that simplifies VPN management tasks. This comprehensive guide walks you through installing WGDashboard on Debian 13, from initial setup to advanced configuration.

Built with Python and Vue.js, WGDashboard offers real-time peer monitoring, QR code generation for mobile devices, and streamlined configuration management. Whether you’re running a home lab or managing remote access for a small business, this tutorial provides everything needed to deploy a fully functional WireGuard management interface on Debian 13 Trixie.

Understanding WGDashboard

WGDashboard serves as a powerful web-based graphical user interface for WireGuard VPN. Instead of manually editing configuration files and executing command-line tools, administrators can manage their entire VPN infrastructure through an accessible browser interface.

The dashboard provides several compelling features that enhance WireGuard management. Real-time connection monitoring displays active peers, data transfer statistics, and handshake information at a glance. QR code generation enables quick mobile device configuration without manual file transfers. The built-in testing tools include ping and traceroute capabilities for troubleshooting connectivity issues directly from the interface.

Configuration management becomes significantly more efficient with WGDashboard. Administrators can create, edit, and delete peers through intuitive forms rather than parsing configuration syntax. Scheduled jobs allow automatic peer restrictions based on time or data usage limits. The dashboard supports multiple WireGuard configurations simultaneously, making it ideal for complex network setups.

Debian 13 receives official support starting with WGDashboard version 4.0 and later releases. The platform runs on Python 3.10, 3.11, or 3.12, all of which are compatible with Debian 13’s package repositories. This compatibility ensures smooth installation without manual Python compilation.

Prerequisites and System Requirements

Hardware Requirements

A modest hardware configuration sufficiently supports WGDashboard for typical deployments. Minimum specifications include 1GB RAM, one CPU core, and 10GB available disk space. These requirements handle basic VPN operations with a handful of connected peers.

For enhanced performance and larger deployments, recommended specifications include 2GB RAM and two CPU cores. These resources provide headroom for multiple simultaneous connections and prevent performance degradation during peak usage. Storage requirements remain minimal since VPN configurations consume negligible disk space.

Software Prerequisites

Debian 13 Trixie must be installed and updated before beginning WGDashboard deployment. A fresh installation works perfectly, though the dashboard integrates seamlessly with existing systems. Root access or sudo privileges are mandatory for installing packages and modifying system configurations.

Several essential packages enable WGDashboard functionality. WireGuard and wireguard-tools provide the core VPN capabilities. Python 3.10 or newer serves as the runtime environment for the dashboard application. Git facilitates repository cloning and future updates. Net-tools provides networking utilities required by the installation script. Finally, iptables manages firewall rules for traffic forwarding.

Network Requirements

Proper network configuration ensures external clients can connect to your WireGuard server. UDP port 51820 (default WireGuard port) must accept incoming connections through your firewall. TCP port 10086 (default dashboard port) requires access for web interface connectivity. These ports can be customized during configuration if defaults conflict with existing services.

A public IP address or properly configured NAT port forwarding enables remote VPN access. Dynamic DNS services work well for home connections with changing IP addresses. DNS configuration access allows customizing resolver settings for connected VPN clients.

Pre-Installation Checks

Verify your Debian version before proceeding. Execute cat /etc/debian_version to confirm Debian 13 installation. The command should return version numbers 13.0 or higher.

Check Python availability with python3 --version. Debian 13 typically includes Python 3.11 by default, which meets WGDashboard requirements perfectly. If Python is missing or outdated, install it through the standard package manager.

Confirm kernel support for WireGuard by running sudo modprobe wireguard followed by lsmod | grep wireguard. Modern Debian 13 kernels include native WireGuard support, eliminating the need for additional kernel modules.

Updating System and Installing Dependencies

System Update

Begin by refreshing package repositories and upgrading existing packages. This ensures all software components include the latest security patches and compatibility improvements. Execute the following command with sudo privileges:

sudo apt update && sudo apt upgrade -y

The update process downloads package metadata from Debian repositories. The upgrade command installs newer versions of currently installed software. The -y flag automatically confirms upgrade prompts, streamlining the process.

System updates provide critical security fixes that protect against known vulnerabilities. Updated packages also ensure compatibility with WGDashboard dependencies. Allow several minutes for completion, depending on how many packages require upgrades.

Installing Core Dependencies

WireGuard forms the foundation of your VPN infrastructure. Install the main package and associated tools with a single command:

sudo apt install wireguard wireguard-tools -y

This installation includes the WireGuard kernel module, command-line utilities like wg and wg-quick, and configuration management tools. Verify successful installation by checking the version:

wg --version

The output should display wireguard-tools version information, confirming proper installation.

Installing Supporting Packages

Several additional packages enable full WGDashboard functionality. Install them together to minimize installation time:

sudo apt install git python3 python3-pip python3-venv net-tools iptables qrencode libqrencode4 -y

Each package serves a specific purpose in the WGDashboard ecosystem. Git enables repository cloning and provides version control for updates. Python3 and python3-pip deliver the runtime environment and package manager. Python3-venv creates isolated virtual environments, preventing dependency conflicts with system packages.

Net-tools includes legacy networking utilities that the installation script references. Iptables manages firewall rules and traffic forwarding configurations. Qrencode and libqrencode4 generate QR codes for mobile device configuration, eliminating manual file transfers.

Verifying Dependencies

Confirm each package installed correctly before proceeding. Check Git installation:

git --version

Verify Python and pip:

python3 --version
pip3 --version

Test qrencode functionality:

qrencode --version

All commands should return version information without errors. If any package fails verification, reinstall it individually using sudo apt install <package-name>.

Installation Method 1: Automated Installation

Cloning the Repository

Navigate to the /opt directory, which conventionally houses optional third-party software on Linux systems:

cd /opt

Clone the official WGDashboard repository from GitHub:

sudo git clone https://github.com/WGDashboard/WGDashboard.git

This command downloads the complete application source code, including installation scripts, dependencies, and documentation. The cloning process typically completes within seconds on modern internet connections.

Navigating to Source Directory

Change into the newly created source directory:

cd WGDashboard/src

The src directory contains the core application files and the primary installation script (wgd.sh). This bash script automates the entire installation process, from dependency installation to service configuration.

Running the Installation Script

Grant execution permissions to the installation script:

sudo chmod u+x wgd.sh

This command adds execute permissions for the file owner, enabling the script to run. Execute the automated installer:

sudo ./wgd.sh install

The installation script performs several critical operations automatically. It creates a Python virtual environment in the current directory, isolating WGDashboard dependencies from system packages. The script installs all required Python modules specified in requirements.txt, including Flask, Gunicorn, and various supporting libraries.

Configuration file templates are copied to appropriate locations. A systemd service unit is created and configured for automatic startup on boot. The installation typically completes within two to five minutes, displaying progress information throughout the process.

During installation, you may see messages about pip upgrades and package installations. These are normal and indicate proper progression. Watch for the success message confirming installation completion.

Setting WireGuard Permissions

WGDashboard requires read and execute permissions on the WireGuard configuration directory:

sudo chmod -R 755 /etc/wireguard

This command recursively applies permissions allowing the dashboard to read configuration files and manage tunnels. The 755 permission set grants full access to the owner while allowing read and execute access for group and others.

Without proper permissions, WGDashboard cannot display existing configurations or create new tunnels. The error manifests as empty configuration lists or permission denied messages in logs.

First-Time Startup

Launch WGDashboard with the startup command:

sudo ./wgd.sh start

The script initiates Gunicorn, a Python WSGI HTTP server that hosts the dashboard application. Gunicorn runs in the background as a daemon process, freeing your terminal for other commands. Startup typically completes within seconds.

Verify the service is running:

sudo ./wgd.sh status

Alternatively, check the systemd service status:

sudo systemctl status wgdashboard

The output should indicate an active (running) state with recent log entries showing successful initialization.

Installation Method 2: One-Command Installation

Official Debian 13 Installation Command

WGDashboard provides a streamlined one-command installation specifically tested for Debian 13. This approach combines system updates, dependency installation, repository cloning, and service setup into a single command sequence.

Execute the comprehensive installation command:

apt-get install sudo git iptables -y && \
sudo apt-get update && \
sudo apt install wireguard-tools net-tools python3 python3-pip python3-venv -y && \
git clone https://github.com/WGDashboard/WGDashboard.git && \
cd ./WGDashboard/src && \
chmod +x ./wgd.sh && \
./wgd.sh install && \
sudo chmod -R 755 /etc/wireguard

This command chain installs prerequisites, clones the repository, executes the installation script, and configures permissions automatically. Each command connects with && operators, ensuring execution halts if any step fails.

Monitoring Installation Progress

The one-command installation displays verbose output throughout execution. Package installation messages appear first, followed by Git cloning progress. The WGDashboard installer outputs detailed information about virtual environment creation and dependency installation.

Watch for error messages or warnings during execution. Most installations complete without issues, but network connectivity problems or repository access issues occasionally occur. If the process stalls, verify internet connectivity and retry the command.

Post-Installation Verification

After installation completes, navigate to the source directory if not already present:

cd /opt/WGDashboard/src

Start the dashboard service:

sudo ./wgd.sh start

Confirm successful startup by checking service status:

sudo systemctl status wgdashboard

The service should display active status with no error messages in recent logs.

Post-Installation Configuration

Enabling IP Forwarding

IP forwarding allows your server to route traffic between networks, essential for VPN functionality. Without IP forwarding enabled, VPN clients cannot access external networks through the tunnel.

Enable IP forwarding temporarily for immediate effect:

sudo sysctl -w net.ipv4.ip_forward=1

Make the change persistent across reboots by adding it to the system configuration:

sudo echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf

Apply the configuration file changes:

sudo sysctl -p /etc/sysctl.conf

Verify the setting took effect:

sysctl net.ipv4.ip_forward

The output should show net.ipv4.ip_forward = 1, confirming IP forwarding is active.

Configuring Firewall Rules

Firewall configuration ensures proper traffic flow while maintaining security. If using UFW (Uncomplicated Firewall), configure it with these commands:

sudo ufw allow 51820/udp
sudo ufw allow 10086/tcp
sudo ufw enable

The first command opens UDP port 51820 for WireGuard VPN traffic. The second opens TCP port 10086 for dashboard web interface access. The final command activates the firewall with new rules.

For iptables-based firewall management, add rules manually:

sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 10086 -j ACCEPT
sudo iptables-save | sudo tee /etc/iptables/rules.v4

These commands append rules to the INPUT chain and persist them across reboots.

Setting Up Systemd Service

Enable WGDashboard to start automatically on system boot:

sudo systemctl enable wgdashboard

This command creates a symbolic link in the systemd startup directory, ensuring the dashboard launches during system initialization.

Start the service immediately:

sudo systemctl start wgdashboard

Verify service status and examine recent logs:

sudo systemctl status wgdashboard

The output displays service state, process ID, memory usage, and recent log entries. Active (running) status indicates successful startup.

Accessing the Dashboard

Open a web browser and navigate to your server’s IP address with port 10086:

http://your-server-ip:10086

Replace your-server-ip with your actual server IP address. For local testing, use http://localhost:10086 or http://127.0.0.1:10086.

The login page appears with fields for username and password. Default credentials are:

• Username: admin
• Password: admin

Change these credentials immediately after first login for security purposes. The dashboard supports modern browsers including Chrome, Firefox, Edge, and Safari.

Initial Dashboard Configuration

Upon first login, navigate to the settings section to change default credentials. Click the settings icon or menu option, typically located in the top-right corner. Locate the account management section and update both username and password.

Choose strong passwords containing at least 16 characters with mixed case letters, numbers, and symbols. Avoid common words or predictable patterns. Store credentials securely using a password manager.

Explore the dashboard interface to familiarize yourself with its layout. The main page displays existing WireGuard configurations and provides options to create new tunnels. Each configuration shows status, peer count, and management options.

Creating Your First WireGuard Configuration

Creating a New Tunnel

From the dashboard home page, click the [+] icon or “Add Configuration” button to initiate tunnel creation. A configuration form appears with fields for tunnel parameters.

Provide a descriptive configuration name that identifies its purpose, such as “HomeVPN” or “OfficeNetwork”. This name appears in the dashboard configuration list and helps distinguish multiple tunnels.

Configure the tunnel IP address using private IP ranges. Common choices include 10.0.0.1/24 for the server address, reserving additional addresses in the subnet for peers. The /24 CIDR notation indicates a subnet mask of 255.255.255.0, providing 254 usable addresses.

Set the listening port, typically 51820 by default. Change this value if running multiple WireGuard instances or if the port conflicts with existing services. Ensure firewall rules match the configured port.

Specify DNS servers for VPN clients. Popular choices include Cloudflare’s 1.1.1.1, Google’s 8.8.8.8, or your local DNS server. Multiple DNS servers provide redundancy if one becomes unavailable.

Understanding Configuration Parameters

WGDashboard automatically generates cryptographic key pairs for each configuration. The private key remains on the server and must never be shared. The public key is distributed to peers for authentication and encryption.

Network subnet selection requires careful planning to avoid conflicts with existing networks. Choose ranges that don’t overlap with your LAN, remote networks, or other VPN configurations. RFC 1918 defines private IP ranges: 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.

MTU (Maximum Transmission Unit) settings affect packet size and can impact performance. The default value of 1420 works well for most scenarios, accounting for WireGuard’s overhead. Lower values may be necessary for networks with restrictive MTU requirements.

Adding Your First Peer

Navigate to your newly created configuration and click “Add Peer” or the [+] icon. The peer creation form contains fields for client configuration.

Provide a descriptive peer name identifying the device or user, such as “John-Laptop” or “iPhone-Personal”. This name helps track which devices have VPN access.

Assign a unique IP address within your tunnel’s subnet. For a server address of 10.0.0.1/24, peer addresses might be 10.0.0.2, 10.0.0.3, and so on. Each peer requires a unique address with /32 notation, indicating a single host.

Configure “Endpoint Allowed IPs” to define which traffic routes through the VPN. Use 0.0.0.0/0 to route all traffic through the VPN, creating a full-tunnel configuration. Specify particular subnets like 192.168.1.0/24 for split-tunnel configurations that only route specific traffic through the VPN.

Enable persistent keepalive for peers behind NAT or firewalls. A value of 25 seconds works well for maintaining connection state. Disable keepalive (set to 0) for peers with stable connections to reduce bandwidth usage.

Add a pre-shared key for enhanced security against potential quantum computing attacks. WGDashboard generates this automatically when enabled. Pre-shared keys provide an additional layer of encryption beyond the standard public-key cryptography.

Generating Client Configuration

After creating a peer, WGDashboard provides multiple options for client configuration distribution. Click the download icon next to the peer to retrieve a .conf file containing all necessary connection parameters.

Transfer the configuration file to the client device and import it into the WireGuard application. Most WireGuard clients support drag-and-drop or file browsing for configuration import.

For mobile devices, use the QR code generation feature. Click the QR code icon next to the peer to display a scannable code. Open the WireGuard mobile app, tap the [+] button, select “Create from QR code”, and scan the displayed code. The app automatically imports all configuration parameters.

Configuration files contain sensitive cryptographic material including private keys. Transmit these files securely using encrypted channels. Delete configuration files from shared locations after client import completes.

WGDashboard Configuration File

Configuration File Location

WGDashboard stores its settings in wg-dashboard.ini, located in the source directory. The default path is /opt/WGDashboard/src/wg-dashboard.ini. This file is automatically generated during first startup if it doesn’t exist.

Access the configuration file with a text editor:

sudo nano /opt/WGDashboard/src/wg-dashboard.ini

The file uses INI format with sections denoted by square brackets and key-value pairs for settings.

Account Settings Section

The [Account] section contains authentication credentials. The username appears in plain text, while the password is stored as a SHA256 hash for security. Modify these values through the dashboard web interface rather than editing the file directly.

Manual password changes require generating SHA256 hashes. Use Python to create a hash:

python3 -c "import hashlib; print(hashlib.sha256('your-password'.encode()).hexdigest())"

Replace your-password with your desired password, then copy the hash output to the configuration file.

Server Settings Section

The [Server] section defines dashboard behavior and paths. Key settings include:

wg_conf_path specifies the WireGuard configuration directory, typically /etc/wireguard. Change this if your configurations reside elsewhere.

app_ip determines which network interface the dashboard binds to. Use 0.0.0.0 to listen on all interfaces, allowing remote access. Set 127.0.0.1 to restrict access to localhost only.

app_port defines the TCP port for dashboard access. The default 10086 can be changed to any available port. Update firewall rules accordingly after port changes.

auth_req toggles authentication requirements. Set to true for password-protected access (recommended) or false to disable authentication (insecure, only for isolated networks).

Dashboard refresh intervals control how frequently the interface updates peer status and statistics. Lower values provide more real-time information but increase server load.

Peer Default Settings

The [Peers] section establishes default values for newly created peers. These settings streamline peer creation by pre-filling common configuration options.

Global DNS server configuration applies to all new peers unless overridden individually. Specify multiple DNS servers separated by commas for redundancy.

Default endpoint allowed IPs define routing behavior for new peers. Set 0.0.0.0/0, ::/0 for full-tunnel routing or specific subnets for split-tunnel configurations.

Remote endpoint configuration specifies the server’s public address and port that clients use to establish connections. Update this when your public IP changes or when using dynamic DNS.

MTU and persistent keepalive defaults apply to all new peers. Adjust these based on network conditions and requirements.

Peer display mode toggles between grid and list views in the dashboard interface. Choose the layout that best suits your preference and screen size.

Editing Configuration Safely

Always stop the dashboard service before editing the configuration file:

sudo ./wgd.sh stop

Or using systemctl:

sudo systemctl stop wgdashboard

Make your edits carefully, preserving the INI file structure. Syntax errors prevent the dashboard from starting correctly.

After saving changes, restart the service:

sudo ./wgd.sh start

Verify successful startup by checking service status and accessing the web interface. Review log files if startup fails, as they contain error messages identifying configuration problems.

Security Best Practices

Changing Default Credentials

Default credentials represent the highest security risk in any web application. Attackers commonly target default usernames and passwords in automated scanning operations. Change credentials immediately after installation, before exposing the dashboard to network access.

Create strong passwords using these guidelines: minimum 16 characters, combination of uppercase and lowercase letters, numbers, and special symbols. Avoid dictionary words, personal information, or predictable patterns. Consider using a password manager to generate and store complex passwords securely.

Change the default username from admin to something less predictable. Generic usernames like admin, root, or administrator are common attack targets. Choose a username that isn’t easily guessed but remains memorable.

Dashboard Access Security

Restrict dashboard access to trusted IP addresses whenever possible. Modify the app_ip setting in the configuration file to bind only to specific interfaces, or implement firewall rules limiting access to authorized networks.

Change the default port 10086 to a non-standard value between 10000 and 65535. This practice, known as security through obscurity, reduces automated scanning effectiveness. Update firewall rules and documentation to reflect the new port number.

Implement a reverse proxy with SSL/TLS encryption for production deployments. Nginx or Apache can terminate SSL connections, forwarding decrypted traffic to the dashboard backend. This approach encrypts credentials and session data during transmission, preventing interception.

Configure HTTPS using Let’s Encrypt certificates for free, automated SSL. Reverse proxy configuration provides centralized certificate management and enables additional security features like HTTP security headers and rate limiting.

WireGuard Configuration Security

Private keys form the foundation of WireGuard security. Protect these keys with strict file permissions, limiting access to root or the WireGuard process user. Never transmit private keys over insecure channels or store them in publicly accessible locations.

Implement pre-shared keys for all peer connections when possible. Pre-shared keys provide quantum-resistant security by adding a symmetric encryption layer to WireGuard’s public-key cryptography. This defense-in-depth approach protects against future cryptographic advances that might compromise current algorithms.

Establish a key rotation schedule for long-lived VPN deployments. Regular key changes limit the impact of potential key compromise and align with security best practices. Plan rotation during maintenance windows to minimize service disruption.

Regularly audit peer access, disabling or removing unused configurations. Each active peer represents a potential security risk if the associated device is lost, stolen, or compromised. Maintain documentation tracking which peers belong to which users or devices.

Firewall Configuration

Implement comprehensive firewall rules using UFW or iptables. Beyond opening required ports, configure default deny policies that block all traffic except explicitly permitted services. This approach minimizes attack surface by preventing access to unnecessary services.

Limit SSH access to specific IP addresses or networks when managing remote servers. Unrestricted SSH access invites brute-force attacks. Consider changing the default SSH port and implementing key-based authentication.

Configure rate limiting for the dashboard port to defend against brute-force authentication attempts. Tools like fail2ban automatically block IP addresses that exceed failed login thresholds.

Monitor firewall logs regularly for suspicious activity. Unusual connection attempts, port scans, or repeated failed authentication attempts may indicate reconnaissance or active attacks. Investigate and block malicious sources promptly.

System Security

Maintain system security through regular updates. Execute sudo apt update && sudo apt upgrade weekly or enable unattended-upgrades for automatic security patch installation. Vulnerabilities in system packages can compromise the entire server, including WGDashboard.

Subscribe to security mailing lists for Debian and WireGuard to receive timely vulnerability notifications. Rapid response to security advisories minimizes exposure windows when exploits become public.

Install and configure fail2ban to protect against brute-force attacks. Fail2ban monitors log files and automatically creates firewall rules blocking IP addresses that exhibit malicious behavior patterns.

Implement comprehensive logging and establish a log monitoring routine. Logs provide visibility into system activities, enabling detection of unauthorized access attempts or unusual behavior. Forward logs to a centralized logging server for analysis and retention.

Backup and Recovery

Regular backups protect against data loss from hardware failure, software bugs, or security incidents. Backup the entire /etc/wireguard/ directory containing all configuration files, keys, and peer definitions.

Export WGDashboard configuration including wg-dashboard.ini and any customizations. Store backups securely with encryption, as they contain sensitive cryptographic material and configuration details.

Test backup restoration procedures periodically to verify backup integrity and familiarize yourself with recovery processes. Documentation without testing often reveals gaps during actual emergencies.

Consider version control for configuration management. Initialize a Git repository in /etc/wireguard/ to track configuration changes over time. This approach provides detailed change history and enables rollback to previous configurations if problems occur.

Managing WGDashboard Service

Starting and Stopping

Control WGDashboard using the provided shell script or systemctl commands. The shell script method provides consistent interface regardless of init system:

sudo ./wgd.sh start
sudo ./wgd.sh stop
sudo ./wgd.sh restart

Navigate to /opt/WGDashboard/src before executing these commands, or specify the full path.

Systemctl commands offer additional control options and integration with system management tools:

sudo systemctl start wgdashboard
sudo systemctl stop wgdashboard
sudo systemctl restart wgdashboard

Restart the service after configuration changes to apply new settings. Some parameters update dynamically, but most require service restart.

Checking Service Status

Monitor service health with status commands that display current state and recent log entries:

sudo systemctl status wgdashboard

The output shows active or inactive status, process ID, memory usage, and recent log messages. Active (running) status indicates normal operation. Failed status suggests problems requiring investigation.

Look for error messages in the status output that indicate specific problems. Common issues include permission errors, port conflicts, or missing dependencies.

Viewing Logs

WGDashboard maintains detailed logs in /opt/WGDashboard/src/log/ directory. Multiple log files track different aspects of operation.

Monitor access logs in real-time to observe dashboard activity:

tail -f /opt/WGDashboard/src/log/access.log

This command displays new log entries as they occur, useful for troubleshooting connection problems or monitoring usage patterns.

Error logs contain detailed information about problems and exceptions:

tail -f /opt/WGDashboard/src/log/error.log

Review error logs when the dashboard behaves unexpectedly or fails to start.

Configure log rotation to prevent log files from consuming excessive disk space. Standard logrotate configuration manages WGDashboard logs alongside other system services.

Enabling Auto-Start on Boot

Configure automatic startup to ensure dashboard availability after system reboots:

sudo systemctl enable wgdashboard

This command creates symbolic links in systemd’s startup directory, triggering dashboard launch during system initialization. The service starts automatically after the network becomes available.

Disable auto-start if the dashboard should only run manually:

sudo systemctl disable wgdashboard

Verify auto-start configuration:

sudo systemctl is-enabled wgdashboard

The output shows enabled or disabled status, confirming current configuration.

Testing and Verification

Dashboard Accessibility Test

Verify dashboard accessibility from multiple locations to ensure proper configuration. Test from the local machine first using:

http://localhost:10086

Successful local access confirms the dashboard is running and responding to requests. Login page appearance indicates correct operation.

Test from another device on the local network using the server’s internal IP address. This verification confirms firewall rules allow local network access. Browser security warnings about insecure connections are expected when using HTTP without SSL.

For external access testing, use the server’s public IP address from outside your network. This test validates port forwarding configuration and firewall rules for remote access. Remember to implement strong authentication and SSL encryption before exposing the dashboard to the internet.

Check browser console for JavaScript errors that might indicate compatibility problems or resource loading failures. Modern browsers’ developer tools provide detailed debugging information.

WireGuard Tunnel Verification

Activate your WireGuard configuration to test tunnel functionality:

sudo wg-quick up wg0

Replace wg0 with your configuration name if different. Successful activation brings up the tunnel interface and applies routing rules.

Verify tunnel status and peer connections:

sudo wg show

This command displays detailed information about active tunnels, including peer public keys, endpoints, allowed IPs, latest handshakes, and data transfer statistics. Recent handshake timestamps indicate active peer connections.

Review handshake times carefully. Handshakes should occur within the last few minutes for active peers. Stale handshakes suggest connectivity problems between peers or configuration errors.

Check data transfer counters to verify traffic flows through the tunnel. Zero transfer values despite active connections might indicate routing problems or client configuration errors.

Connectivity Testing

From a connected VPN client, ping the server’s tunnel IP address to verify basic connectivity:

ping 10.0.0.1

Successful pings confirm the tunnel is operational and routing traffic correctly. Ping failures suggest firewall rules, routing problems, or incorrect configuration.

Execute traceroute commands to diagnose routing paths:

traceroute 10.0.0.1

Traceroute output shows each network hop between source and destination. For VPN connections, traffic should route directly through the tunnel without intermediate hops.

Test DNS resolution to verify DNS server configuration:

nslookup google.com

Proper DNS resolution confirms clients can resolve hostnames through configured DNS servers. Resolution failures prevent accessing websites by name despite working internet connectivity.

Verify internet connectivity through the VPN by accessing external websites. For full-tunnel configurations, all traffic should route through the VPN server. Check your apparent IP address using services like whatismyip.com to confirm traffic exits through the VPN.

Dashboard Features Testing

Navigate through dashboard sections to verify all functionality works correctly. Test configuration editing by modifying a peer’s description or allowed IPs. Save changes and confirm they persist after page refresh.

Generate QR codes for test peers and verify they display correctly. QR code generation failures indicate missing dependencies or permission problems.

Use built-in ping and traceroute tools from the dashboard interface. These integrated diagnostic tools help troubleshoot connectivity issues without switching to command-line interfaces.

Add and remove test peers to confirm full CRUD (Create, Read, Update, Delete) functionality. Verify that changes made through the dashboard appear in underlying WireGuard configuration files.

Common Troubleshooting

Dashboard Won’t Start

The error message “gunicorn: command not found” indicates missing Python virtual environment dependencies. This problem commonly occurs on Debian 12 and 13 when python3-venv isn’t installed.

Resolve the issue by installing the virtual environment package:

sudo apt install python3-venv -y

Navigate to the WGDashboard source directory and reinstall:

cd /opt/WGDashboard/src
sudo ./wgd.sh install

The reinstallation recreates the virtual environment with proper dependencies. Confirm successful installation by starting the dashboard.

Check Python version compatibility if installation continues failing. WGDashboard requires Python 3.10, 3.11, or 3.12. Verify installed version with python3 --version.

Cannot Access Dashboard

Service status verification is the first troubleshooting step when dashboard access fails:

sudo systemctl status wgdashboard

Inactive or failed status indicates the service isn’t running. Review error messages in the status output and log files for specific failure causes.

Firewall rules commonly block dashboard access. Verify port 10086 (or your configured port) accepts incoming connections:

sudo ufw status

Or for iptables:

sudo iptables -L -n | grep 10086

Add missing firewall rules if necessary.

Confirm you’re using the correct IP address and port. Common mistakes include using the wrong network interface IP or forgetting to specify the port number. The complete URL should be http://IP:10086.

Review the app_ip setting in wg-dashboard.ini. If set to 127.0.0.1, only local connections succeed. Change to 0.0.0.0 to accept connections from all interfaces.

Permission Denied Errors

Permission errors prevent WGDashboard from reading WireGuard configurations or modifying settings. The dashboard requires read and execute permissions on /etc/wireguard/.

Apply correct permissions:

sudo chmod -R 755 /etc/wireguard

Verify file ownership matches the user running WGDashboard. By default, the dashboard runs as root through systemd, providing access to protected directories.

Check specific file permissions if problems persist:

ls -la /etc/wireguard/

Configuration files should be readable by the dashboard process. Private key files require restricted permissions (600) to prevent unauthorized access while remaining readable by the process owner.

Peer Connection Failures

Clients cannot connect when port forwarding is misconfigured on routers or firewalls. Verify your router forwards UDP port 51820 to your WireGuard server’s internal IP address.

Confirm the public IP address configured in peer endpoint settings matches your actual public IP. Dynamic IP addresses change periodically, breaking existing configurations. Implement dynamic DNS services for automatic address updates.

Review the “Endpoint Allowed IPs” settings for each peer. This parameter defines which destination IPs route through the VPN. Incorrect settings prevent traffic from flowing through the tunnel.

Examine firewall rules on both server and client machines. Overly restrictive rules block legitimate VPN traffic. Ensure UDP port 51820 accepts incoming connections on the server and outgoing connections on clients.

Validate configuration file syntax carefully. Minor typos in public keys, IP addresses, or other parameters prevent successful connections. WireGuard provides minimal error messages, making syntax errors difficult to diagnose.

Installation Script Errors

Missing dependencies cause installation script failures. Ensure all required packages are installed before running the installer:

sudo apt install git python3 python3-pip python3-venv wireguard-tools net-tools -y

Network connectivity problems during git clone manifest as timeout errors or partial downloads. Verify internet access and retry the command. Consider using a different network if problems persist.

Python virtual environment creation fails when disk space is insufficient. Check available space with df -h and free up space if necessary. The virtual environment requires at least 100MB for dependencies.

Repository access problems occasionally occur when GitHub experiences outages or rate limiting. Wait a few minutes and retry the installation. Alternative mirrors or repository downloads provide workarounds for persistent access problems.

Dashboard Performance Issues

Slow dashboard response often results from excessive refresh intervals. Adjust the refresh rate in settings to reduce server load. Longer intervals between updates improve performance for systems with many peers.

Monitor system resource usage with htop or top to identify bottlenecks. Insufficient RAM causes swapping, dramatically reducing performance. CPU constraints affect dashboard responsiveness and WireGuard throughput.

Large peer counts increase dashboard load as it queries status for each peer. Optimize performance by grouping peers into separate configurations or upgrading server hardware for large deployments.

Network latency between the dashboard server and client browser affects perceived performance. Implement a reverse proxy with caching to improve response times for static resources.

Advanced Configuration Tips

Reverse Proxy Setup

Nginx provides robust reverse proxy capabilities with SSL/TLS termination. Install Nginx on your Debian system:

sudo apt install nginx -y

Create a configuration file for WGDashboard at /etc/nginx/sites-available/wgdashboard:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:10086;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Enable the configuration by creating a symbolic link:

sudo ln -s /etc/nginx/sites-available/wgdashboard /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Install Certbot for Let’s Encrypt SSL certificates:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d your-domain.com

Certbot automatically configures SSL and sets up certificate renewal.

Multi-Configuration Management

WGDashboard supports multiple WireGuard tunnels simultaneously. Create additional configurations through the dashboard interface, each with unique names and network subnets.

Organize configurations by purpose for clarity. Separate configurations for different user groups, network segments, or security zones simplify management. Examples include employee access, contractor access, and site-to-site connections.

Switch between configurations using the dashboard’s configuration selector. Each configuration manages independently, allowing different peers, settings, and routing rules.

Scheduled Peer Management

Implement automatic peer restrictions using WGDashboard’s scheduled jobs feature. Create time-based access controls that disable peers during specific hours or days.

Configure data limit enforcement to prevent bandwidth abuse. Set transfer quotas per peer, automatically disabling connections when limits are exceeded. This feature proves valuable for shared VPN infrastructure with multiple users.

Schedule regular peer audits to review and remove inactive configurations. Automated reporting identifies peers that haven’t connected within specified timeframes.

Custom DNS Configuration

Integrate Pi-hole with WGDashboard for network-wide ad blocking. Configure Pi-hole as the DNS server in your WireGuard configuration. All DNS queries from VPN clients flow through Pi-hole, filtering advertisements and tracking domains.

Set up split-tunnel DNS configurations that route internal domain queries to corporate DNS servers while sending external queries to public resolvers. This approach optimizes resolution performance and maintains security for internal resources.

Implement DNS leak prevention by configuring explicit DNS servers in WireGuard configurations. Without proper DNS configuration, clients may use their default DNS servers, exposing queries outside the VPN tunnel.

Integration with External Tools

Prometheus monitoring integration provides detailed metrics collection for WGDashboard and WireGuard. Export peer connection status, data transfer rates, and system health metrics for long-term analysis.

Create Grafana dashboards visualizing WireGuard performance and usage patterns. Grafana’s rich graphing capabilities transform raw metrics into actionable insights about VPN infrastructure health.

Develop automated backup scripts that regularly export configurations and archive them securely. Shell scripts with cron scheduling provide reliable backup automation without manual intervention.

Updating WGDashboard

Checking for Updates

Navigate to the WGDashboard installation directory:

cd /opt/WGDashboard

Check for available updates by fetching the latest repository information:

git fetch origin
git status

The output indicates whether local code matches the remote repository. Messages about being behind the origin branch signal available updates.

Performing Updates

Stop the dashboard service before updating to prevent file conflicts:

sudo systemctl stop wgdashboard

Backup current configuration and data:

sudo cp -r /opt/WGDashboard /opt/WGDashboard.backup
sudo cp -r /etc/wireguard /etc/wireguard.backup

Pull the latest changes from the repository:

git pull origin main

Navigate to the source directory and run the update command:

cd /opt/WGDashboard/src
sudo ./wgd.sh update

The update script installs new dependencies and applies necessary migrations. Restart the service after update completion:

sudo systemctl start wgdashboard

Verify successful update by checking the version number in the dashboard interface and confirming normal operation.

Version Management

Check your current version through the dashboard’s about or settings section. Version numbers appear in the interface footer or system information page.

Review changelog and release notes on the GitHub repository before updating. Release notes document new features, bug fixes, and breaking changes that might affect your deployment.

Roll back to previous versions if updates cause problems. With backups in place, restore previous versions using:

sudo systemctl stop wgdashboard
sudo rm -rf /opt/WGDashboard
sudo mv /opt/WGDashboard.backup /opt/WGDashboard
sudo systemctl start wgdashboard

Git provides version control features for precise version management. Check out specific releases or commits:

git checkout v4.0

Replace v4.0 with your desired version tag.

Congratulations! You have successfully installed WGDashboard. Thanks for using this tutorial for installing WGDashboard GUI management of WireGuard VPN servers on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official WGDashboard website.