# WireGuard VPN Server Stack

> Modern VPN with WireGuard, web UI, and monitoring.

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: wireguard, wg-easy, prometheus, grafana
- Tags: wireguard, vpn, security, tunnel, privacy
- Source: https://docker.recipes/homelab/wireguard-vpn-complete

## Overview

WireGuard represents a paradigm shift in VPN technology, offering a modern alternative to traditional solutions like OpenVPN and IPsec. Developed by security researcher Jason Donenfeld, WireGuard leverages state-of-the-art cryptography including Curve25519, ChaCha20, and Poly1305 to deliver exceptional performance while maintaining a minimal codebase of just 4,000 lines. This simplicity reduces attack surface and makes security auditing feasible, while achieving speeds 3-4x faster than OpenVPN through its kernel-level implementation.

This monitoring-enabled stack combines WireGuard's core VPN capabilities with wg-easy's intuitive web interface, Prometheus metrics collection, and Grafana visualization dashboards. The wg-easy component eliminates WireGuard's traditionally complex configuration process, providing QR code generation for mobile devices and streamlined peer management. Meanwhile, the wireguard-exporter feeds connection metrics, bandwidth usage, and peer statistics into Prometheus, which Grafana transforms into actionable monitoring dashboards for tracking VPN performance and usage patterns.

This configuration particularly benefits homelab enthusiasts, small businesses, and development teams who need enterprise-grade VPN monitoring without the complexity of traditional solutions. The stack provides visibility into which peers are connected, bandwidth consumption per client, connection stability metrics, and historical usage patterns - intelligence typically reserved for expensive commercial VPN solutions.

## Features

- ChaCha20-Poly1305 authenticated encryption with Curve25519 key exchange
- Web-based peer management with QR code generation for mobile clients
- Real-time metrics collection for bandwidth usage and connection statistics
- Cryptokey routing for automatic peer-to-peer connectivity
- Mobile roaming support with seamless IP address transitions
- PromQL-powered analytics for complex VPN usage queries
- Automatic peer handshake monitoring and connection health tracking
- Multi-dimensional labeling for per-client bandwidth and uptime analysis

## Use cases

- Homelab remote access with usage monitoring and client tracking
- Small office site-to-site connectivity with bandwidth analytics
- Development team secure access to staging environments with audit trails
- IoT device management with per-device connection monitoring
- Remote work infrastructure with employee usage reporting
- Gaming server access with latency and connection quality metrics
- Privacy-focused browsing with data usage tracking and performance monitoring

## Prerequisites

- Minimum 512MB RAM for monitoring stack (256MB WireGuard + 256MB Prometheus/Grafana)
- UDP port 51820 forwarded through firewall for WireGuard traffic
- Public IP address or dynamic DNS domain for WG_HOST variable
- Basic understanding of VPN networking and port forwarding concepts
- Linux kernel with WireGuard module support (kernel 5.6+ or backport module)
- Router administrative access for port forwarding configuration

## docker-compose.yml

```yaml
services:
  wg-easy:
    image: weejewel/wg-easy:latest
    environment:
      - WG_HOST=${WG_HOST}
      - PASSWORD=${WG_PASSWORD}
      - WG_PORT=51820
      - WG_DEFAULT_DNS=1.1.1.1
      - WG_ALLOWED_IPS=0.0.0.0/0
    volumes:
      - wg_data:/etc/wireguard
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    networks:
      - wg_net

  wireguard-exporter:
    image: mindflavor/prometheus-wireguard-exporter:latest
    cap_add:
      - NET_ADMIN
    network_mode: host
    command:
      - -n
      - /etc/wireguard/wg0.conf
    volumes:
      - wg_data:/etc/wireguard:ro

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    networks:
      - wg_net

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    networks:
      - wg_net

volumes:
  wg_data:
  prometheus_data:
  grafana_data:

networks:
  wg_net:
```

## .env

```bash
# WireGuard VPN
WG_HOST=your.public.ip.or.domain
WG_PASSWORD=secure_admin_password
GRAFANA_PASSWORD=secure_grafana_password

# WG-Easy UI at http://localhost:51821
# VPN port: 51820/UDP
```

## Usage notes

- WG-Easy UI at http://localhost:51821
- VPN connects on port 51820/UDP
- Download client configs from UI
- Forward port 51820/UDP on router
- Set WG_HOST to public IP/domain

## Troubleshooting

- Clients can't connect after setup: Verify WG_HOST matches your actual public IP or DDNS hostname exactly
- wireguard-exporter shows no metrics: Ensure /etc/wireguard/wg0.conf exists and has proper permissions for container access
- High memory usage in Prometheus: Reduce retention period or increase --storage.tsdb.retention.time to manage data retention
- wg-easy UI inaccessible: Check that port 51821 isn't blocked by host firewall and container has proper NET_ADMIN capabilities
- Peers lose connection frequently: Verify net.ipv4.ip_forward=1 sysctl is applied and not overridden by host networking
- Grafana dashboards empty: Confirm prometheus.yml targets include wireguard-exporter:9586 and Prometheus can scrape metrics

