izetmolla/wireguard-router repository overview

⁠WireGuard VPN Client Router for Docker Networks

This image runs a WireGuard VPN client inside a Docker container and acts as a gateway for a Docker network to reach one or more remote subnets behind the VPN.

Features

• Runs on Ubuntu 25.10 (minimal build, no systemd)
• Acts as a WireGuard client and Docker network router
• Configurable Docker network CIDR and remote LAN subnets via environment variables
• Accepts WireGuard config from a mounted file or environment variables
• NAT (MASQUERADE) so remote networks do not need a return route
• Manual DNS handling (no systemd-resolved / resolvconf dependency)

⁠📦 Image

Docker Hub: izetmolla/wireguard-router:latest
GitHub: This repository

⁠🛠 Requirements

• Host must support /dev/net/tun and CAP_NET_ADMIN in Docker
• WireGuard kernel module loaded on host:

  sudo modprobe wireguard
  

  Copy
• Docker 20.10+ or Podman with equivalent capabilities

⁠⚙️ Environment Variables

⁠📄 Providing the WireGuard Config

⁠Option 1: Mount a Config File

docker run -it --rm   --cap-add NET_ADMIN   --device /dev/net/tun   -e DOCKER_NET_CIDR=10.10.12.0/24   -e REMOTE_LAN_CIDRS="10.20.20.0/24 192.168.50.0/24"   -v $(pwd)/wg0.conf:/etc/wireguard/wg0.conf:ro   izetmolla/wireguard-router:latest

⁠Option 2: Provide as Plain Text via WG_CONF

docker run -it --rm   --cap-add NET_ADMIN   --device /dev/net/tun   -e DOCKER_NET_CIDR=10.10.12.0/24   -e REMOTE_LAN_CIDRS="10.20.20.0/24"   -e WG_CONF="[Interface]\nPrivateKey=...\nAddress=10.8.0.2/24\n\n[Peer]\nPublicKey=...\nEndpoint=example.com:51820\nAllowedIPs=0.0.0.0/0"   izetmolla/wireguard-router:latest

⁠Option 3: Provide as Base64 via WG_CONF_B64

export WG_CONF_B64=$(base64 -w0 wg0.conf)

docker run -it --rm   --cap-add NET_ADMIN   --device /dev/net/tun   -e DOCKER_NET_CIDR=10.10.12.0/24   -e REMOTE_LAN_CIDRS="10.20.20.0/24"   -e WG_CONF_B64="$WG_CONF_B64"   izetmolla/wireguard-router:latest

⁠🐳 Docker Compose Example

version: "3.8"

networks:
  vpn-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.10.12.0/24

services:
  wgclient:
    image: izetmolla/wireguard-router:latest
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    volumes:
      - ./wg0.conf:/etc/wireguard/wg0.conf:ro
    environment:
      DOCKER_NET_CIDR: "10.10.12.0/24"
      REMOTE_LAN_CIDRS: "10.20.20.0/24 192.168.50.0/24"
      VPN_DNS: "1.1.1.1,1.0.0.1"
    networks:
      vpn-net:
        ipv4_address: 172.28.0.254
    restart: unless-stopped

  app1:
    image: alpine:3.20
    networks: [vpn-net]
    cap_add: [NET_ADMIN] 
    entrypoint: [
      "sh", "-c",
      "apk add --no-cache iproute2 && ip route add 10.20.20.0/24 via 172.28.0.254 && sleep infinity"
    ]

⁠🔌 How It Works

1. Validates required env vars and WireGuard config.
2. Brings up WireGuard interface via wg-quick.
3. Configures iptables rules:
   • Forwards traffic between DOCKER_NET_CIDR and each REMOTE_LAN_CIDRS subnet.
   • MASQUERADE outbound so no return route is needed on the VPN server.
4. Sets DNS manually to avoid systemd dependencies.
5. Acts as a router for any container on the same Docker network.

⁠🛑 Common Errors

• Missing DOCKER_NET_CIDR → Set the Docker network CIDR in env.
• No WireGuard config provided → Provide WG_CONF, WG_CONF_B64, or mount a file.
• Permission denied on /dev/net/tun → Run container with --device /dev/net/tun and CAP_NET_ADMIN.

⁠📜 License

MIT License.
See LICENSE⁠ file for details.

⁠🤝 Contributing

Pull requests and issues are welcome! Please ensure changes are tested before submission.