Infrastructure guide
WireGuard Setup: A Recoverable Remote-Access Plan
Configure WireGuard with narrow routes, deliberate DNS and firewall behavior, safe keys, external tests, revocation, and lockout recovery.
Published and reviewed by OpenAlt · October 1, 2026
OpenAlt’s verdict: use native WireGuard by default, with narrow routes and a documented rescue path. Use containers only when they solve a documented constraint. The central tradeoff is deployment speed versus recovery when routing, DNS, or keys are wrong.
Treat private remote access as one system: identity, routes, name resolution, firewall policy, testing, and recovery must agree.
Table of Contents
- Install natively unless a container solves a documented constraint
- Map peers, tunnel addresses, subnets, DNS and public endpoint
- Generate and store keys safely
- Configure server and one client with narrow AllowedIPs
- Forwarding/firewall plus split versus full tunnel
- Test handshake, routes, DNS, MTU and a truly external network
- Revocation, rotation, backup and out-of-band recovery
- Troubleshoot absent handshake, no traffic and no DNS
- FAQ
1. Install natively unless a container solves a documented constraint
Use the host’s native WireGuard package by default because interfaces, keys, routes, and service ownership remain visible in the operating system. Choose a container only when you can name the constraint it solves and document its privileges, persistence, upgrades, and recovery procedure.
The official installation guide lists packages by operating system. Confirm the host platform, package source, service manager, and configuration persistence rather than treating installation as universal copy and paste.
Before production, a wireguard docker compose deployment should document:
- Required host interfaces and kernel features
- Private-key and configuration storage
- Upgrade and persistence behavior
- Local console, provider console, or other out-of-band access
- The procedure for disabling or reversing the tunnel
2. Map peers, tunnel addresses, subnets, DNS and public endpoint
Write the network map first: identify the server, every client peer, the tunnel subnet, reachable private subnets, DNS resolvers, public endpoint, and exposed UDP port. This prevents overlapping addresses and makes every AllowedIPs choice deliberate.
Choose a tunnel range that does not overlap with networks clients may use at home, work, in hotels, or in the cloud. Assign one tunnel address per peer. Record whether the endpoint is a stable hostname or address, which UDP port is exposed, and which internal names clients must resolve.
| Item | Example planning value |
|---|---|
| Server tunnel address | One reserved address in the tunnel subnet |
| Client tunnel address | One unique address per device |
| Reachable subnet | Only the private range the peer needs |
| DNS | An explicitly selected internal or public resolver |
| Endpoint | Public hostname or address plus UDP port |
WireGuard separates interfaces, keys, peers, endpoints, AllowedIPs, and optional keepalive behavior. Keep those concepts distinct in your notes; the official Quickstart explains their relationships.
3. Generate and store keys safely
Treat each peer’s private key as a credential. Generate keys on the device or trusted administration system that will use them, keep private material out of chat and tickets, and make protected backups only when recovery requires them.
The public-key peer model and UDP tunnel design are central to WireGuard; the WireGuard paper describes both. Pair every peer name with its public key, tunnel address, owner, purpose, and revocation status.
Use separate keys for separate devices. A lost phone should not require replacing a laptop’s authorization.
- Restrict private-key file permissions.
- Avoid committing secrets to repositories.
- Keep recovery copies encrypted and access-controlled.
- Record public keys and peer ownership in an inventory.
4. Configure server and one client with narrow AllowedIPs
Start with one client and the smallest useful route set. On the server, define the client’s public key and tunnel address. On the client, define the server peer, endpoint, server public key, and only the destinations that should traverse the tunnel.
For split tunneling, include the tunnel subnet and specific private subnets or hosts the peer needs. For full tunneling, route broader traffic through the server only after planning DNS, forwarding, firewall rules, and egress policy. The Quickstart documents AllowedIPs, endpoints, peers, and keepalive.
Verify that:
- The client has a unique tunnel address.
- Each side references the other side’s public key.
- The endpoint is reachable from outside.
AllowedIPsdo not overlap unexpectedly.
Add destinations incrementally and record why each route exists.
5. Forwarding/firewall plus split versus full tunnel
A successful cryptographic handshake does not make private services reachable. Configure kernel forwarding, firewall policy, and route scope separately; forwarding is an explicit kernel routing responsibility, as described in the kernel IP sysctl documentation.
For split tunneling, permit only tunnel-to-private-subnet traffic the peer needs and leave ordinary internet traffic on its existing path. For full tunneling, define forwarding and outbound policy before sending client internet traffic through the server.
At minimum:
- Allow the WireGuard UDP listener at the public edge.
- Permit tunnel traffic only toward intended destinations.
- Keep management ports outside the tunnel until recovery is proven.
- Decide whether return routes or address translation are required.
- Document each rule’s source, destination, and purpose.
If an application sits behind a reverse proxy, keep responsibilities distinct. OpenAlt’s Caddy Docker Compose guide and Traefik Docker Compose guide can help with proxy structure; WireGuard should provide private reachability, not an unclear application boundary.
6. Test handshake, routes, DNS, MTU and a truly external network
Test in layers, beginning with the handshake and ending on an external network. A reliable test proves that keys match, intended routes exist, packets return, names resolve, and the tunnel works away from the local LAN.
Use a phone hotspot, public Wi-Fi, or another genuinely separate connection. Use the Quickstart to interpret endpoint reachability, keepalive, and peer state.
- The client receives its planned tunnel address.
- The server records a recent handshake.
- The client route table contains only intended destinations.
- A permitted private IP responds.
- An internal hostname resolves through the selected DNS path.
- A real application works, not merely a ping.
- Large transfers and interactive sessions are acceptable.
- The documented rescue path still works.
If small requests work but larger ones fail, treat MTU as an operational hypothesis. Change one value at a time, retest externally, and record the result.
7. Revocation, rotation, backup and out-of-band recovery
A recoverable wireguard self hosted service needs a written peer lifecycle: add, inventory, revoke, rotate, back up, and restore. Recovery cannot depend on the tunnel because a bad route, expired key, or broken firewall may prevent access.
Keep an encrypted backup of server configuration and peer inventory, with access limited to recovery owners. Preserve peer names, public keys, tunnel addresses, routes, DNS decisions, firewall intent, and the public endpoint.
When a device is lost or retired, remove its peer authorization and issue a new key for its replacement. Rotate keys according to policy, testing the replacement before removing the old path when safe.
Document the out-of-band access method, tunnel-disable procedure, known-good configuration, backup location, restore owner, and the order for restoring forwarding, firewall, DNS, and peers.
8. Troubleshoot absent handshake, no traffic and no DNS
Troubleshoot in dependency order: no handshake indicates endpoint, port, key, or reachability problems; a handshake with no traffic indicates routes, forwarding, firewall, or return-path problems; working traffic with failed names indicates DNS.
For an absent handshake, confirm the endpoint, public keys, UDP listener, and external path. For no traffic, compare the client’s AllowedIPs with the destination and inspect forwarding and firewall intent. For no DNS, identify the resolver in use and verify that it is reachable through the selected route.
Keep an evidence log with the peer, time, observed state, changed setting, and next test. Do not broaden every route reflexively. When the goal is remote media access, compare this plan with OpenAlt’s Jellyfin remote-access guide. Use the RTO/RPO impact calculator to set recovery priorities.
FAQ
Should I use wireguard docker compose?
Use it when the container solves a documented constraint, such as an established deployment boundary or repeatable workflow. Keep native installation as the simpler default otherwise. Document persistence, privileges, key storage, upgrades, and out-of-band recovery first.
Which AllowedIPs should I use for split tunnel?
Use the tunnel subnet plus only the private subnets or hosts the client needs. Add destinations incrementally and test from an external network. See WireGuard’s Quickstart.
What if I lock myself out?
Use local console, provider console, or another out-of-band method to disable or repair the tunnel. Keep management access outside the tunnel until recovery is tested, and preserve a known-good configuration.
Does WireGuard replace an application proxy?
No. WireGuard supplies private peer connectivity; application exposure, TLS termination, and proxy routing remain separate. Use narrow routes for network access, then configure the application boundary deliberately. Consult the relevant OpenAlt Caddy or Traefik guidance when needed.