Remote Site VPN Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Remote Site VPN Setup Guide

Introduction

A way into a second location (a cabin, a parent's house, a small office) that keeps working when your usual remote tools don't. If the Cloudflare tunnel or Guacamole at the remote site is down, you can still connect, reach the remote PC, and from there reach anything on that network.

This guide runs a WireGuard server in Docker on a PC at the remote site, keeps its address current with a small DDNS container, and optionally links your home machines to it. It uses three files from compose/server5/:

File What it does
wireguard-server.yaml The remote site's own VPN server
cottage-ddns.yaml Keeps cabin-vpn.example.com pointed at the site's current public IP
wireguard-client.yaml Optional: the remote PC also dials out to your home VPN, as a second way in

Example addresses: remote VPN 10.20.0.0/24 (server 10.20.0.1), remote LAN 192.168.50.0/24, home LAN 192.168.1.0/24, home VPN 10.8.0.0/24.


Before You Start: Make the Two Networks Different

Many ISP routers ship with the same default range (often 192.168.1.0/24 or 192.168.2.0/24). If the remote LAN uses the same range as home, a device at home can't tell which side an address belongs to, and routing between them breaks.

Change the remote router's LAN (DHCP) range to something unused, for example 192.168.50.0/24, before setting up the VPN. Reserve a fixed address for the remote PC while you're there.


Step 1: Port Forward at the Remote Site

On the remote router, forward UDP 51820 to the remote PC. This needs someone on that network, or remote access to the router's admin page (for example through Guacamole while it still works).

Step 2: Keys and Configs

Generate keys on any machine with WireGuard installed (one pair for the server, one per client, plus a preshared key per client for extra protection):

wg genkey | tee server.key | wg pubkey > server.pub
wg genkey | tee laptop.key | wg pubkey > laptop.pub
wg genpsk > laptop.psk

Server (appdata/wireguard-server/config/wg_confs/wg0.conf on the remote PC, never in git):

[Interface]
Address = 10.20.0.1/24
ListenPort = 51820
PrivateKey = <server.key>
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth+ -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth+ -j MASQUERADE

[Peer] # Laptop
PublicKey = <laptop.pub>
PresharedKey = <laptop.psk>
AllowedIPs = 10.20.0.2/32

The PostUp lines let VPN clients reach the remote LAN through the container.

Client (laptop or phone):

[Interface]
Address = 10.20.0.2/32
PrivateKey = <laptop.key>
MTU = 1280

[Peer]
PublicKey = <server.pub>
PresharedKey = <laptop.psk>
Endpoint = cabin-vpn.example.com:51820
AllowedIPs = 10.20.0.0/24, 192.168.50.0/24
PersistentKeepalive = 25

Only the remote ranges go through this tunnel, so it can stay on alongside your home VPN. Make a spare client or two now; adding peers later means editing the server file on the remote PC.

Step 3: The Server Container

compose/server5/wireguard-server.yaml:

services:
  wireguard-server:
    container_name: wireguard-server.${HOST_NAME}
    image: lscr.io/linuxserver/wireguard:latest
    cap_add: [NET_ADMIN, SYS_MODULE]
    environment:
      PUID: ${PUID}
      PGID: ${PGID}
      TZ: ${TZ}
    ports:
      - "51820:51820/udp"
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv4.ip_forward=1
    volumes:
      - ${DOCKERDIR}/wireguard-server/config:/config
      - /lib/modules:/lib/modules:ro
    restart: unless-stopped

Because a wg_confs/wg0.conf exists, the image runs it as-is instead of generating peers.

Step 4: Keep the Address Current

compose/server5/cottage-ddns.yaml uses favonia/cloudflare-ddns, which updates only the record you name:

services:
  cottage-ddns:
    container_name: cottage-ddns.${HOST_NAME}
    image: favonia/cloudflare-ddns:latest
    environment:
      CLOUDFLARE_API_TOKEN: ${COTTAGE_DDNS_TOKEN}
      DOMAINS: cabin-vpn.example.com
      PROXIED: "false"          # WireGuard is UDP; Cloudflare's proxy can't carry it
      IP6_PROVIDER: none
    read_only: true
    cap_drop: [all]
    security_opt: [no-new-privileges:true]
    restart: unless-stopped

Create the token in Cloudflare under My Profile → API Tokens with Zone → DNS → Edit, limited to your one zone, and put it in .env as COTTAGE_DDNS_TOKEN. Create the DNS record once (type A, DNS only) or let the container create it.

Step 5: Start and Test

On the remote PC:

git pull
docker compose -p mediaserver -f docker-compose-server5.yaml up -d wireguard-server cottage-ddns
docker logs wireguard-server.<host>

Test from outside that network, for example a phone on mobile data: connect the client, then ping 10.20.0.1 and a device on 192.168.50.x.


Optional: Your Home Machines as Clients

  • A home Windows PC can run the remote client tunnel as a second service next to its own wg-server. See Running a Second Tunnel on the Same Windows PC.
  • The remote PC can dial home (wireguard-client.yaml): it joins your home VPN as a client, routing only the home VPN range (AllowedIPs = 10.8.0.0/24), with network_mode: host so SSH on the PC answers on its VPN address. Because it dials out, it needs no port forward at the remote site. It's a useful second path in case the remote router's forward is lost.

Troubleshooting

  • No handshake: check the port forward, that cabin-vpn.example.com resolves to the site's current IP (docker logs cottage-ddns.<host>), and that the record is DNS only.
  • Connected but can't reach remote devices: the remote LAN range in the client's AllowedIPs is wrong, or the PostUp NAT lines are missing.
  • Home stops working while connected: the remote and home LANs use the same range. Renumber the remote router.
  • Adding a client later: add a [Peer] to wg0.conf on the remote PC, then docker restart wireguard-server.<host>.
⚠️ **GitHub.com Fallback** ⚠️