WireGuard Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

WireGuard Setup Guide

Introduction

WireGuard is a fast, simple VPN. With it you can reach everything on your home network from anywhere (your NAS, Home Assistant, admin pages) without exposing those services to the internet.

This repository uses WireGuard three ways:

Setup Where it runs Guide
Home VPN server on a Windows PC Windows (WireGuard app as a service) Windows server below
Home VPN server in Docker Linux or NAS (linuxserver/wireguard) Docker server below
Remote site VPN (for example a cabin) plus site-to-site links Remote PC in Docker Remote Site VPN Setup Guide

Addresses below are examples: home LAN 192.168.1.0/24, router 192.168.1.1, Pi-hole 192.168.1.5, VPN clients 10.8.0.0/24. Pick a VPN range that doesn't overlap any network you'll connect from.

Table of Contents


Before You Start

  1. Port forward UDP 51820 on your router to the machine running the server.
  2. A name for your home address. Most home connections change IP now and then. Use a DNS name that stays current, for example vpn.example.com kept up to date by Cloudflare DDNS Setup Guide. It must be DNS only (grey cloud) in Cloudflare: Cloudflare's proxy can't carry WireGuard's UDP traffic.
  3. Pick your client DNS. Pointing clients at your Pi-hole gives them ad blocking and your local names while away.

Windows Server (Home VPN)

This runs a reliable full-tunnel server on Windows 10/11 using Windows' built-in NAT. No Internet Connection Sharing, no IPv6 changes, no PostUp scripts.

Step 1: Install and create the tunnel

  1. Install WireGuard from wireguard.com/install.
  2. Add Tunnel → Add empty tunnel, name it wg-server. Windows generates the server key.
  3. Fill in the server configuration:
    [Interface]
    PrivateKey = <generated>
    Address = 10.8.0.1/24
    ListenPort = 51820
    
    # One [Peer] per client
    [Peer]
    # Phone
    PublicKey = <client public key>
    AllowedIPs = 10.8.0.2/32
    The server doesn't need AllowedIPs = 0.0.0.0/0, PostUp/PostDown rules, or IPv6 disabled.

Step 2: Run it as a service

The tunnel then starts with Windows, before anyone logs in:

& "C:\Program Files\WireGuard\wireguard.exe" /installtunnelservice "C:\Program Files\WireGuard\Data\Configurations\wg-server.conf.dpapi"

Check services.msc for WireGuard Tunnel: wg-server, startup type Automatic.

Step 3: NAT for the VPN range

This lets clients use the PC's connection to reach the LAN and the internet:

New-NetNat -Name "WG-NAT" -InternalIPInterfaceAddressPrefix 10.8.0.0/24

It only applies to 10.8.0.x, doesn't touch the PC's own internet, and is safe to leave in place when WireGuard is stopped. With WinNAT you don't need to turn on IP forwarding (IPEnableRouter) for clients to reach the LAN.

Optional: clients talking to each other. By default one VPN client can't reach another through the server. If you want that (for example to reach a remote-site PC that is also a client), turn on forwarding for the tunnel: Set-NetIPInterface -InterfaceAlias "wg-server" -Forwarding Enabled.

Step 4: Firewall

New-NetFirewallRule -DisplayName "WireGuard UDP 51820" -Direction Inbound -Protocol UDP -LocalPort 51820 -Action Allow
New-NetFirewallRule -DisplayName "WG LAN Access" -Direction Inbound -Action Allow -InterfaceAlias "wg-server"

Saving changes in the WireGuard app restarts the tunnel, and Windows may set its network profile back to Public. Rules made with profile Any (the default above) keep working either way.

Step 5: Check it

& "C:\Program Files\WireGuard\wg.exe" show     # needs an elevated prompt

Without admin rights, Get-NetNatSession and Get-NetAdapterStatistics -Name wg-server still show live client traffic.


Docker Server

On Linux or a NAS, linuxserver/wireguard builds the server and client configs for you.

  1. Copy compose/templates/wireguard.yaml into your server folder and set:
    • SERVERURL: your DNS name, for example vpn.example.com
    • PEERS: client names, for example phone,laptop
    • PEERDNS: your Pi-hole, for example 192.168.1.5
    • INTERNAL_SUBNET: the VPN range, for example 10.8.0.0
    • ALLOWEDIPS: 0.0.0.0/0 for everything, or 192.168.1.0/24 for the LAN only
  2. Start it:
    docker compose -p mediaserver -f docker-compose-server1.yaml up -d wireguard
  3. Client configs and QR codes appear in appdata/wireguard/config/peer_<name>/. Show a QR code in the terminal:
    docker exec -it wireguard.<host> /app/show-peer phone

WireGuard YAML

Pin the image tag. A linuxserver/wireguard update in 2025 changed the Alpine/iptables base and stopped some tunnels passing traffic. Pinning a known-good tag avoids surprise breakage; read the changelog before moving it.


Client Configurations

Phone or laptop, full tunnel (all traffic goes home, so you get your Pi-hole and your home IP):

[Interface]
PrivateKey = <client private key>
Address = 10.8.0.2/32
DNS = 192.168.1.5
MTU = 1280

[Peer]
PublicKey = <server public key>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Split tunnel (only home traffic goes through the VPN; better for streaming over the VPN, since video doesn't detour through home): replace AllowedIPs with 192.168.1.0/24, 10.8.0.0/24.

MTU = 1280 avoids stalls on mobile networks and hotel Wi-Fi. PersistentKeepalive = 25 keeps the tunnel open through NAT.

Test from the client:

ping 192.168.1.1                  # router
nslookup example.com 192.168.1.5  # Pi-hole answers
curl https://icanhazip.com        # full tunnel: shows your home IP

Adding and Removing Clients

  1. Generate keys for the client:
    wg genkey | tee client.key | wg pubkey > client.pub
    The WireGuard apps can also generate the key pair for you.
  2. Add a [Peer] with the client's public key and the next free address to the server. Each client needs its own address and key pair; never share one config between two devices.
  3. Write the client config with that same address.
  4. To remove a client, delete its [Peer] from the server and delete its key files.

Keep a short list of which address belongs to which device. A config whose Address doesn't match the server's AllowedIPs for that key still handshakes, so it looks connected, but every packet is dropped. If a client "connects but nothing works", compare those two first.


Running a Second Tunnel on the Same Windows PC

A Windows PC that runs wg-server can also be a client of another WireGuard server, for example to keep a link open to a remote site. The WireGuard app normally lets only one tunnel be active at a time, so run the second one as its own service:

& "C:\Program Files\WireGuard\wireguard.exe" /installtunnelservice "C:\path\to\Remote-Site.conf"

Both run side by side. Make sure the client tunnel's AllowedIPs only covers the remote site's ranges (for example 10.20.0.0/24, 192.168.50.0/24), never 0.0.0.0/0 or your home LAN, or it will steal the PC's own traffic. Remove it with:

& "C:\Program Files\WireGuard\wireguard.exe" /uninstalltunnelservice Remote-Site

See Remote Site VPN Setup Guide.


Troubleshooting

  • No handshake: the port isn't forwarded, the DNS name points at an old IP, or the name is proxied (orange cloud) in Cloudflare. Check with wg show.
  • Handshake but no traffic: address mismatch between client and server (see above), or the NAT/firewall step was skipped.
  • Works on Wi-Fi, stalls on mobile data: lower MTU to 1280.
  • Can't reach LAN names, only IPs: set DNS to your Pi-hole and include your local domain, for example DNS = 192.168.1.5, lan.
  • Streaming stutters over the VPN: use a split tunnel so the stream doesn't make a round trip through home.
  • Docker image error manifest unknown: the tag you pinned no longer exists; pick a current one from the linuxserver releases page.
⚠️ **GitHub.com Fallback** ⚠️