WireGuard on Docker

Why run WireGuard on Docker?

• Portability: A Dockerized WireGuard setup can be moved between hosts with consistent behavior.
• Reproducibility: Container images and compose files capture configuration in code.
• Isolation: WireGuard runs inside its own namespace, reducing cross-service exposure when paired with other containers.
• Ease of updates: You can pin versions, test changes, and roll back more cleanly.

However, there are trade-offs. WireGuard touches network stack and kernel interfaces, so your Docker host must be prepared to support the VPN’s needs. You’ll likely need elevated privileges or specific capabilities, and you’ll want to plan for persistent keys and configs.

Core concepts and prerequisites

What you need from the host

• A Linux kernel with WireGuard support (most modern distros include this. You may need to install wireguard-tools or wireguard-dkms).
• Docker host that can expose or map the necessary network interfaces to the container.
• Sufficient privileges to create and manage network namespaces and interfaces (often via CAP_SYS_ADMIN or using the host’s wireguard adapters).

Key files and components

• Configs: wg0.conf or similar, containing private keys, peers, allowed IPs, and endpoints.
• Keys: private and public keys for both server and clients.
• DNS and routing: the container should have a reliable DNS resolution and correct IP routing rules to send traffic through the tunnel.

Security considerations

• Keep keys out of image layers. Mount them as volumes or use secrets management.
• Use non-root users inside containers where possible, but WireGuard generally requires privileged capabilities.
• Limit container exposure. Don’t expose the VPN port unnecessarily to the public internet.

Setting up WireGuard in Docker: a practical pattern

There are several ways to approach this, from a minimal single-container setup to a more robust, swarm-orchestrated arrangement. Below is a practical, commonly used pattern using a dedicated WireGuard container with a host network mode suitable for simple use cases, and a more isolated Docker network approach for more complex environments.

Basic single-container, host network approach

• Use a Docker image that includes WireGuard tools and a minimal init or entrypoint to start wg-quick or a custom script.
• Run with network: "host" to give the container direct access to the host’s network stack. This is simple but less isolated.
• Mount config and keys into the container, and ensure the container has CAP_SYS_ADMIN and NET_ADMIN capabilities.

Example (conceptual):

• docker run, name wg -d, cap-add=NET_ADMIN, cap-add=SYS_MODULE, device /dev/net/tun, network host -v /path/to/wg:/etc/wireguard my-wg-image
• Inside the container, start wg-quick up wg0.

More isolated approach with bridge networking

• Create a dedicated docker network for the VPN container and use a small sidecar to push traffic through the tunnel.
• Use a custom entrypoint to configure the interface inside the container and route traffic via the wg0 interface.

Persistent keys and configs

• Store wg0.conf and private keys on the host and mount them into the container as read-only or with controlled permissions.
• Consider a small initialization script that validates the config and checks for key freshness on startup.

Example docker-compose pattern

A typical docker-compose for a WireGuard container might look like this:

• version: "3.9"
• services:
• wireguard: image: ghcr.io/linuxserver/wireguard:latest container_name: wireguard cap_add:
• NET_ADMIN
• SYS_MODULE environment:
• PUID=1000
• PGID=1000
• TZ=Etc/UTC
• SERVERURL=your.public.endpoint
• SERVERPORT=51820 volumes:
• /path/to/wg:/config
• /lib/modules:/lib/modules:ro ports:
• "51820:51820/udp" sysctls:
• net.ipv4.ip_forward=1
• net.ipv6.conf.all.forwarding=1 restart: unless-stopped

Notes: WireGuard on Ubuntu

• This example uses a well-known community image that includes a ready-to-go WireGuard setup. You can also build your own image if you need custom tooling or a leaner footprint.
• SERVERURL and SERVERPORT must match your host’s accessible endpoint and port used for peers.

How to configure peers and routing

Server/client roles

• Server: the central endpoint that peers connect to. It holds the private key and manages the internal WG interface.
• Clients/Peers: other devices that connect to the server, each with their own keys and AllowedIPs.

AllowedIPs

• For a typical site-to-site or point-to-site setup, you’ll specify:
• 0.0.0.0/0 to route all traffic through the VPN (full-tunnel).
• Specific subnets for partial routing.
• The server will advertise its kid and your peers’ public keys, and you’ll exchange config files accordingly.

Routing table considerations

• In a container, ensure the wg0 interface can be created and that the host routes can be updated.
• If you route client traffic through the VPN, you’ll need proper NAT rules on the host (e.g., using iptables or nftables) to masquerade outbound traffic.

A quick comparison: host network vs isolated network for WireGuard in Docker

Common pitfalls and how to avoid them

• Kernel/Module issues: If your host doesn’t have the WireGuard kernel module loaded, the container won’t create wg0. Ensure /dev/net/tun exists and load the module (modprobe wireguard or wireguard kernel module via dkms).
• Capabilities: NET_ADMIN and SYS_MODULE are commonly required. If you’re on a restrictive host or using a minimalist distro, you may need extra permissions.
• Persisted data: Don’t bake private keys into the image. Use host volumes or a secrets mechanism, and set file permissions carefully (e.g., 600 for private keys).
• DNS leaks: If you route all traffic through the VPN, ensure DNS queries also go through the tunnel, or you may get DNS leaks if the host’s DNS resolver is used outside the tunnel.
• Client revocation: Plan for key rotation and revocation. Have a way to revoke a client’s peer configuration without rebuilding the entire server container.

Monitoring and maintenance

• Logs: Enable verbose logs during setup, then scale back once stable. Look for messages about interface creation, peer authentication, and route changes.
• Health checks: Implement a simple health check that tests the wg interface status (e.g., wg show) and connectivity to a known endpoint.
• Backups: Regularly back up wg0.conf, private keys, and peer configurations. Store them securely outside the container.
• Updates: Pin specific image versions and test updates in a staging environment before rolling out to production. WireGuard config changes should be versioned with your infra as code process.

When to consider alternatives or enhancements

• If you need multi-host or cloud-native scaling, consider using a dedicated VPN mesh or a modern network overlay that integrates with your orchestration system.
• For very small, single-machine use, a direct host-based WireGuard setup without Docker may be simpler and easier to troubleshoot.
• If you require complex client management, look into automation tools that integrate with WireGuard (e.g., generating keys, updating peers, and revoking access programmatically).

Final recommendation

If your goal is reproducible, portable VPN deployments with straightforward management, running WireGuard on Docker is a strong choice. Start with a trusted, well-maintained image and a host network or isolated pattern that matches your security posture. Use volumes for keys and configs, grant only the necessary capabilities, and implement a clear upgrade and key management process. For teams new to Docker networking, begin with a minimal host-network setup to validate the configuration, then migrate to a more isolated architecture as you scale.

In short: Docker brings consistency and automation to WireGuard deployments, but you must handle kernel compatibility, capabilities, and secure storage with care. With a carefully designed compose or orchestration setup, WireGuard on Docker becomes a robust, maintainable VPN solution.