# WireGuard Easy with UI

> Easy WireGuard VPN setup with web-based management interface and QR code generation.

- Category: Security & Networking
- Difficulty: beginner
- Components: wg-easy, nginx
- Tags: vpn, wireguard, wg-easy, networking
- Source: https://docker.recipes/security/wireguard-easy-stack

## Overview

WireGuard Easy (wg-easy) is a simplified management interface for WireGuard VPN that eliminates the complexity of traditional VPN server administration. Created to address WireGuard's command-line complexity, wg-easy provides a web-based dashboard for managing VPN clients, generating configuration files, and creating QR codes for mobile device setup. The project transforms WireGuard's powerful but technical foundation into an accessible solution for users who need VPN functionality without extensive networking expertise. This stack combines wg-easy with NGINX to create a production-ready VPN solution with enhanced security and traffic management. NGINX serves as a reverse proxy, providing SSL termination, rate limiting, and additional security layers for the wg-easy web interface. The combination addresses common VPN deployment challenges including certificate management, traffic routing, and client onboarding through QR codes. Organizations benefit from this pairing because NGINX handles the web traffic complexities while wg-easy manages VPN client lifecycle, creating a robust solution that scales from personal use to enterprise deployments. This configuration suits network administrators seeking modern VPN infrastructure, remote teams requiring secure connectivity, and organizations transitioning from legacy VPN solutions to WireGuard's superior performance and security model.

## Features

- Interactive web dashboard for WireGuard client management with real-time connection status
- Automatic QR code generation for instant mobile client configuration
- One-click client creation and deletion with automatic key pair generation
- Real-time bandwidth monitoring and connection statistics per client
- NGINX reverse proxy with SSL/TLS termination and security headers
- Built-in DNS configuration management for VPN clients
- Automatic IP address allocation within defined subnets
- Password-protected web interface with bcrypt hash authentication

## Use cases

- Remote work infrastructure for distributed teams needing secure office network access
- Homelab enthusiasts creating personal VPN servers for secure internet browsing
- Small business secure connectivity for employees accessing internal resources
- Development teams requiring secure connections to staging and production environments
- Educational institutions providing VPN access for students and faculty
- Content creators and digital nomads needing geo-location flexibility
- Organizations migrating from expensive commercial VPN solutions to self-hosted alternatives

## Prerequisites

- Server with public IP address and UDP port 51820 accessible from internet
- Minimum 512MB RAM recommended for concurrent client connections
- Domain name or static IP for WG_HOST environment variable configuration
- Basic understanding of VPN networking concepts and subnet configuration
- SSL certificate files if enabling HTTPS through NGINX reverse proxy
- Administrative access to router/firewall for port forwarding configuration

## docker-compose.yml

```yaml
services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:latest
    environment:
      WG_HOST: ${WG_HOST}
      PASSWORD_HASH: ${PASSWORD_HASH}
      WG_DEFAULT_ADDRESS: ${WG_DEFAULT_ADDRESS}
      WG_DEFAULT_DNS: ${WG_DEFAULT_DNS}
      WG_ALLOWED_IPS: ${WG_ALLOWED_IPS}
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    volumes:
      - wg-easy:/etc/wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    networks:
      - vpn-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - wg-easy
    networks:
      - vpn-net
    restart: unless-stopped

volumes:
  wg-easy:

networks:
  vpn-net:
    driver: bridge
```

## .env

```bash
# WireGuard Host (public IP or domain)
WG_HOST=vpn.example.com

# Password Hash (generate with: wgpw YOUR_PASSWORD)
PASSWORD_HASH=

# Client Configuration
WG_DEFAULT_ADDRESS=10.8.0.x
WG_DEFAULT_DNS=1.1.1.1
WG_ALLOWED_IPS=0.0.0.0/0, ::/0
```

## Usage notes

- Web UI at http://localhost:51821
- Generate QR codes for mobile clients
- Port 51820/UDP must be accessible from internet
- Use wgpw command to generate password hash

## Troubleshooting

- wg-easy container fails to start with 'Operation not permitted': Ensure Docker has NET_ADMIN and SYS_MODULE capabilities enabled on host system
- Clients can connect but cannot access internet: Verify net.ipv4.ip_forward=1 sysctl setting and check server firewall rules for IP masquerading
- Web interface shows 'Incorrect password' with correct credentials: Regenerate PASSWORD_HASH using bcrypt and ensure no trailing whitespace in environment variable
- QR codes not generating or displaying blank: Check that WG_HOST environment variable contains externally accessible IP or domain name
- VPN clients connect but have no internet access: Verify WG_DEFAULT_DNS is set to accessible DNS servers like 1.1.1.1 or 8.8.8.8
- NGINX proxy returns 502 Bad Gateway: Ensure wg-easy service is running and accessible on port 51821 within Docker network

