michaelschiemer/deployment/wireguard/QUICKSTART.md

WireGuard VPN - Quick Start Guide

Minimalistisches Host-based WireGuard Setup in 5 Minuten.

Prerequisites

• Debian/Ubuntu Server mit Root-Zugriff
• Public IP oder DynDNS
• Ports 51820/udp offen in Firewall/Router

Installation (Server)

Option 1: Automated (Ansible) - Empfohlen

# 1. Cleanup altes Docker-Setup (falls vorhanden)
cd /home/michael/dev/michaelschiemer/deployment/scripts
sudo ./cleanup-old-wireguard.sh

# 2. Deploy WireGuard Host-based
cd /home/michael/dev/michaelschiemer/deployment/ansible
ansible-playbook playbooks/setup-wireguard-host.yml

# 3. Verify Installation
sudo wg show wg0
sudo systemctl status wg-quick@wg0

Option 2: Manual Installation

# Install WireGuard
sudo apt update
sudo apt install wireguard wireguard-tools qrencode nftables

# Generate Server Keys
cd /etc/wireguard
sudo wg genkey | sudo tee server_private.key | wg pubkey | sudo tee server_public.key

# Create Config (replace YOUR_SERVER_IP)
sudo tee /etc/wireguard/wg0.conf <<EOF
[Interface]
PrivateKey = $(sudo cat server_private.key)
Address = 10.8.0.1/24
ListenPort = 51820
PostUp = sysctl -w net.ipv4.ip_forward=1
EOF

# Enable and Start
sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0

# Apply Firewall
# See: deployment/ansible/templates/wireguard-host-firewall.nft.j2

Client Setup

Generate Client Config

# On server
cd /home/michael/dev/michaelschiemer/deployment/scripts
sudo ./generate-client-config.sh michael-laptop

# Script outputs:
# - Config file: ../wireguard/configs/michael-laptop.conf
# - QR code (text): ../wireguard/configs/michael-laptop.qr.txt
# - QR code (PNG): ../wireguard/configs/michael-laptop.qr.png

Import on Client

Linux/macOS:

# Copy config to client
scp server:/path/to/michael-laptop.conf /etc/wireguard/

# Connect
sudo wg-quick up michael-laptop

# Verify
ping 10.8.0.1
curl -k https://10.8.0.1:8080  # Traefik Dashboard

Windows:

1. Download WireGuard from https://www.wireguard.com/install/
2. Open WireGuard GUI
3. Click "Import tunnel(s) from file"
4. Select michael-laptop.conf
5. Click "Activate"

iOS/Android:

1. Install WireGuard app from App Store/Play Store
2. Tap "+" → "Create from QR code"
3. Scan QR code (shown in terminal or PNG file)
4. Tap "Activate"

Service Access

Nach VPN-Verbindung sind folgende Services erreichbar:

Service	URL	Purpose
Traefik Dashboard	https://10.8.0.1:8080	Reverse Proxy Management
Prometheus	http://10.8.0.1:9090	Metrics Collection
Grafana	https://10.8.0.1:3001	Monitoring Dashboards
Portainer	http://10.8.0.1:9000	Docker Management
Redis Insight	http://10.8.0.1:8001	Redis Debugging

Verification

# On Client after connecting VPN

# Test VPN connectivity
ping 10.8.0.1

# Test service access
curl -k https://10.8.0.1:8080  # Traefik Dashboard (should return HTML)
curl http://10.8.0.1:9090      # Prometheus (should return HTML)

# Check routing
ip route | grep 10.8.0.0

# Verify WireGuard interface
sudo wg show

Troubleshooting

Cannot connect to VPN

# On Server
sudo wg show wg0              # Check if interface exists
sudo systemctl status wg-quick@wg0  # Check if service running
sudo ss -ulnp | grep 51820    # Check if listening on port

# Check firewall allows WireGuard port
sudo nft list ruleset | grep 51820

# View logs
sudo journalctl -u wg-quick@wg0 -f

VPN connected but cannot access services

# On Client
ping 10.8.0.1  # Should work

# On Server
sudo nft list ruleset | grep "10.8.0.0"  # Check VPN network allowed

# Check service is listening
sudo ss -tlnp | grep 8080  # Traefik Dashboard
sudo docker ps             # Check containers running

Slow connection

# Check MTU settings (on client)
sudo wg show michael-laptop

# Try reducing MTU if packet loss
# Edit config: MTU = 1420 (in [Interface] section)

Security

• ✅ All admin services only accessible via VPN
• ✅ Public ports limited to 80, 443, 22
• ✅ Modern crypto (ChaCha20, Poly1305)
• ✅ Preshared keys for quantum resistance
• ✅ nftables firewall with explicit rules

Next Steps

• Add more clients: sudo ./generate-client-config.sh <device-name>
• Setup monitoring alerts for VPN
• Optional: Add minimal CoreDNS for .internal domains
• Schedule key rotation (recommended: annually)

Support

Full documentation: deployment/wireguard/README.md

For issues, check:

• sudo journalctl -u wg-quick@wg0
• sudo dmesg | grep wireguard
• sudo nft list ruleset