azinchen/wireguard repository overview

⁠WireGuard VPN Docker Container

A WireGuard node in a small self-configuring Docker container: a server for your devices with zero-config peer provisioning (keys, addresses, configs and QR codes generated for you), per-peer exits — straight out, through an upstream VPN container, through a WireGuard provider, or through another peer such as a home router — a fail-closed nftables kill switch on every path, and hot reload of everything without dropping tunnels. The same image is a WireGuard sidecar for other containers.

⁠✨ Key Features

• 🧩 Zero-config peers — PEERS=alice,bob generates keys, addresses, configs and QR codes (details⁠)
• 🔑 Bring your own keys — a peer may give only its public key; no private key on the server (details⁠)
• 🚪 Per-peer exits — direct, an upstream VPN container, a provider conf, or another peer (details⁠)
• 🏠 Exit nodes — exit=true makes a peer such as a home router an exit; config generated (details⁠)
• 🛡️ Fail-closed kill switch — if an upstream is down, its peers lose internet, never leak (details⁠)
• 🔄 Hot reload — wg-reload applies the peers file in place, unchanged peers keep sessions (details⁠)
• 🧭 DNS-named gateways — sidecars and endpoints by hostname, re-resolved and re-routed live (details⁠)
• 🔗 Sidecar mode — LOCAL_GATEWAY tunnels the container and network_mode: service: clients (details⁠)
• 🩺 Opt-in health monitor — HEALTHCHECK for the interface, routing tables and egress probes (details⁠)
• 📊 Built-in reporting — peer-report shows handshake, traffic and exit per peer (details⁠)
• 🐧 Kernel WireGuard — uses the host module when present, falls back to wireguard-go (details⁠)
• 📦 Small multi-arch Alpine image — 386, amd64, arm/v6, arm/v7, arm64, riscv64 (details⁠)

⁠🚀 Quick Start

# docker-compose.yml
services:
  wireguard:
    image: azinchen/wireguard:latest
    container_name: wireguard
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
    sysctls:
      - net.ipv4.ip_forward=1
    ports:
      - 51820:51820/udp
    environment:
      - SERVER_ENDPOINT=vpn.example.com     # what your devices dial
      - PEERS=alice,bob
    volumes:
      - ./volumes/config:/etc/wireguard

docker compose up -d
docker exec wireguard peer-conf alice --qr     # scan with the WireGuard app
docker exec wireguard peer-conf bob > bob.conf # or import the file
docker exec wireguard peer-report              # who is connected, through which exit

⁠🧩 Common Setups

Per-peer exits are one file:

# volumes/config/peers.conf
alice   gw=nl                    # out through the nordvpn-wg container "nl"
bob                              # direct (default)
carol   gw=home                  # out through the home router
home    exit=true                # the home router: dial-in exit node, everything generated
site-a  allowed=192.168.50.0/24  # a site behind the peer, reachable from the VPN

with VPN_GATEWAYS=nl=nordvpn-wg in the environment (a DNS name on the Docker network). docker exec wireguard peer-conf home prints the config the router imports.

⁠⚙️ Environment Variables

Grouped by feature; every variable is one line here — the Configuration Reference⁠ has the full descriptions.

⁠Core networking

⁠Peers — details⁠

⁠IPv6

⁠Gateway mode — details⁠

⁠Exit nodes and upstreams — details⁠

⁠Sidecar mode — details⁠

⁠Health monitor — details⁠

⁠🛠️ Operator Commands

⁠📋 Runtime Requirements

• --cap-add=NET_ADMIN and --sysctl net.ipv4.ip_forward=1 — interfaces, routes and nftables; forwarding peer traffic (details⁠)
• a kernel with WireGuard support (5.6+ built in, or the wireguard module); without it the container falls back to userspace wireguard-go, which additionally needs --device /dev/net/tun and is slower (details⁠)
• a published UDP port for wg0 (51820 by default), plus one per dial-in exit node (details⁠)
• for IPv6 peers: --sysctl net.ipv6.conf.all.forwarding=1 and an IPv6-routed Docker network (details⁠)

⁠🐛 Issues

If you have any problems with or questions about this image, please open a GitHub issue⁠.

Check the Troubleshooting⁠ wiki page first — and attach the output of the built-in diagnostic to any report:

docker exec wireguard network-diagnostic

For how the container works under the hood, see Architecture and Internals⁠; for building it yourself, image tags and releases, Building and CI⁠.

⁠📄 License

MIT — see LICENSE⁠.