WireGuard VPN

intermediate

Modern, fast VPN server.

Overview

WireGuard is a modern VPN protocol that revolutionizes secure networking through state-of-the-art cryptography and a minimal codebase. Developed by Jason Donenfeld and officially integrated into the Linux kernel in 2020, WireGuard delivers superior performance compared to legacy protocols like OpenVPN and IPSec while maintaining enterprise-grade security. Its cryptokey routing approach and streamlined design eliminate the complexity and overhead that plague traditional VPN solutions. This WireGuard deployment leverages the LinuxServer.io container image to provide a complete VPN server solution with automatic peer configuration and certificate management. The container handles all cryptographic key generation, peer relationship establishment, and network routing configuration automatically, while exposing the standard WireGuard UDP port 51820 for client connections. The setup includes kernel module loading capabilities and proper network administration privileges to enable full VPN functionality. This configuration is ideal for network administrators seeking high-performance VPN infrastructure, homelab enthusiasts building secure remote access solutions, and organizations requiring fast site-to-site connectivity. The automatic QR code generation and mobile app compatibility make client onboarding effortless, while the kernel-level implementation ensures maximum throughput for bandwidth-intensive applications like media streaming and file synchronization.

Key Features

Modern ChaCha20 encryption with Poly1305 authentication for quantum-resistant security
Automatic peer configuration with QR code generation for mobile device setup
Cryptokey routing that eliminates complex firewall rules and routing tables
Kernel-level implementation providing near-native network performance
Built-in connection roaming support for seamless network transitions
Minimal attack surface with only 4,000 lines of code versus OpenVPN's 100,000+
Automatic DNS configuration with PEERDNS for transparent name resolution
Cross-platform client support for iOS, Android, Windows, macOS, and Linux

Common Use Cases

1Homelab remote access for managing servers and services from anywhere
2Secure site-to-site connectivity between office locations or data centers
3Mobile workforce VPN providing fast, reliable connections for remote employees
4Privacy-focused browsing through encrypted tunnel routing
5Media server access for streaming personal content while traveling
6Developer environment access for remote coding and testing workflows
7IoT device management through secure tunneled connections to embedded systems

Prerequisites

Docker host with NET_ADMIN and SYS_MODULE capabilities enabled
Minimum 128MB RAM allocated for container and peer management
UDP port 51820 forwarded through firewall and router configuration
Public IP address or dynamic DNS service for SERVERURL configuration
Basic understanding of VPN networking concepts and IP addressing
WireGuard client applications installed on devices requiring VPN access

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  wireguard: 
3    image: linuxserver/wireguard:latest
4    container_name: wireguard
5    restart: unless-stopped
6    cap_add: 
7      - NET_ADMIN
8      - SYS_MODULE
9    environment: 
10      PUID: 1000
11      PGID: 1000
12      TZ: UTC
13      SERVERURL: ${SERVER_URL}
14      SERVERPORT: 51820
15      PEERS: ${PEERS}
16      PEERDNS: auto
17    volumes: 
18      - wireguard_config:/config
19      - /lib/modules:/lib/modules
20    ports: 
21      - "51820:51820/udp"
22    sysctls: 
23      - net.ipv4.conf.all.src_valid_mark=1
24
25volumes: 
26  wireguard_config:

.env Template

.env

1SERVER_URL=your-server-ip
2PEERS=3

Usage Notes

1Docs: https://docs.linuxserver.io/images/docker-wireguard/
2QR codes generated in /config/peerX/peerX.png
3Forward UDP port 51820 on your router
4Scan QR code with WireGuard app (iOS/Android/desktop)
5Set PEERS=phone,laptop,tablet for named configs
6Fastest VPN protocol - better performance than OpenVPN

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  wireguard:
5    image: linuxserver/wireguard:latest
6    container_name: wireguard
7    restart: unless-stopped
8    cap_add:
9      - NET_ADMIN
10      - SYS_MODULE
11    environment:
12      PUID: 1000
13      PGID: 1000
14      TZ: UTC
15      SERVERURL: ${SERVER_URL}
16      SERVERPORT: 51820
17      PEERS: ${PEERS}
18      PEERDNS: auto
19    volumes:
20      - wireguard_config:/config
21      - /lib/modules:/lib/modules
22    ports:
23      - "51820:51820/udp"
24    sysctls:
25      - net.ipv4.conf.all.src_valid_mark=1
26
27volumes:
28  wireguard_config:
29EOF
30
31# 2. Create the .env file
32cat > .env << 'EOF'
33SERVER_URL=your-server-ip
34PEERS=3
35EOF
36
37# 3. Start the services
38docker compose up -d
39
40# 4. View logs
41docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/wireguard/run | bash

Troubleshooting

Connection timeout on port 51820: Verify UDP port forwarding is configured on your router and firewall rules allow traffic
Module not found errors: Ensure /lib/modules volume mount matches your host kernel version and modules are available
QR codes not generating in /config/peerX/: Check container has write permissions to mounted volume and PEERS environment variable is properly set
DNS resolution failing for clients: Verify PEERDNS setting and ensure your DNS server is reachable from the WireGuard network subnet
High CPU usage during connections: Confirm your kernel supports WireGuard natively, otherwise the container falls back to slower userspace implementation
Mobile app cannot import configuration: Ensure QR code images are fully generated and try manual configuration file import instead

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

wireguard

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download