WireGuard Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki
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, router192.168.1.1, Pi-hole192.168.1.5, VPN clients10.8.0.0/24. Pick a VPN range that doesn't overlap any network you'll connect from.
- Before You Start
- Windows Server (Home VPN)
- Docker Server
- Client Configurations
- Adding and Removing Clients
- Running a Second Tunnel on the Same Windows PC
- Troubleshooting
-
Port forward UDP
51820on your router to the machine running the server. -
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.comkept 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. - Pick your client DNS. Pointing clients at your Pi-hole gives them ad blocking and your local names while away.
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.
- Install WireGuard from wireguard.com/install.
-
Add Tunnel → Add empty tunnel, name it
wg-server. Windows generates the server key. - Fill in the server configuration:
The server doesn't need
[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
AllowedIPs = 0.0.0.0/0, PostUp/PostDown rules, or IPv6 disabled.
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.
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/24It 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.
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.
& "C:\Program Files\WireGuard\wg.exe" show # needs an elevated promptWithout admin rights, Get-NetNatSession and Get-NetAdapterStatistics -Name wg-server still show live client traffic.
On Linux or a NAS, linuxserver/wireguard builds the server and client configs for you.
- Copy
compose/templates/wireguard.yamlinto your server folder and set:-
SERVERURL: your DNS name, for examplevpn.example.com -
PEERS: client names, for examplephone,laptop -
PEERDNS: your Pi-hole, for example192.168.1.5 -
INTERNAL_SUBNET: the VPN range, for example10.8.0.0 -
ALLOWEDIPS:0.0.0.0/0for everything, or192.168.1.0/24for the LAN only
-
- Start it:
docker compose -p mediaserver -f docker-compose-server1.yaml up -d wireguard
- 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

Pin the image tag. A
linuxserver/wireguardupdate 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.
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 = 25Split 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- Generate keys for the client:
The WireGuard apps can also generate the key pair for you.
wg genkey | tee client.key | wg pubkey > client.pub
- 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. - Write the client config with that same address.
- 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.
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-SiteSee Remote Site VPN Setup Guide.
-
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
MTUto1280. -
Can't reach LAN names, only IPs: set
DNSto your Pi-hole and include your local domain, for exampleDNS = 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.