entrptaher/wireguard repository overview

⁠WireGuard Docker Image

A minimal, production-ready Docker image for running a WireGuard VPN server.
No web UI or reverse proxy is included by default, but you can easily extend with your own services (see Caddy example below).

⁠Features

• Runs the official WireGuard kernel module and tools
• Simple configuration via mounted files and environment variables
• Healthcheck and automatic restart support
• Multi-architecture support (amd64, arm64, etc.)

⁠Quick Start (WireGuard Only)

1. Prepare Your WireGuard Configs

Create a configs directory and place your WireGuard configuration file(s) (e.g., wg0.conf) inside it.

2. Example docker-compose.yml:

version: '3.8'

services:
  wireguard:
    image: entrptaher/wireguard:latest
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    devices:
      - /dev/net/tun
    sysctls:
      net.ipv4.conf.all.src_valid_mark: 1
    environment:
      - BYPASS_IPS=100.103.22.36   # Optional: set to your bypass IPs or remove
    volumes:
      - ./configs:/etc/wireguard-configs:ro  # Place your WireGuard .conf files here
    ports:
      - 51820:51820/udp           # Match this to your WireGuard ListenPort
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/healthcheck.sh"]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 5s

3. Start the Service

docker compose up -d

⁠Advanced Example: WireGuard + Caddy Reverse Proxy

You can run additional services (like a reverse proxy) inside the WireGuard network namespace.
Below is an example where Caddy runs as a reverse proxy, sharing the WireGuard container’s network stack.

Example docker-compose.yml:

version: '3.8'

services:
  wireguard:
    image: entrptaher/wireguard:latest
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    devices:
      - /dev/net/tun
    sysctls:
      net.ipv4.conf.all.src_valid_mark: 1
    environment:
      - BYPASS_IPS=100.103.22.36
    volumes:
      - ./configs:/etc/wireguard-configs:ro
    ports:
      - 51820:51820/udp
      - 8000:80           # Expose Caddy's HTTP port via WireGuard container
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/healthcheck.sh"]
      interval: 10s
      timeout: 10s
      retries: 3
      start_period: 5s

  caddy:
    image: caddy:latest
    container_name: caddy
    network_mode: "service:wireguard"   # Shares network with WireGuard
    command: >
      caddy reverse-proxy
        --change-host-header
        --from :80
        --to https://ip.me:443
    depends_on:
      - wireguard
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:80"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

How it works:

• The Caddy container shares the WireGuard container’s network namespace.
• All traffic from Caddy will go through the VPN tunnel.
• Caddy listens on port 80 (exposed as 8000 on the host via the WireGuard service).

⁠Environment Variables

• BYPASS_IPS
  (optional)
  Comma-separated list of IPs to bypass the VPN tunnel.

⁠Volumes

• /etc/wireguard-configs
  Mount your directory of WireGuard configuration files here (read-only).

⁠Ports

• 51820/udp
  Exposes the WireGuard VPN port (adjust as needed).
• 8000:80
  (Optional) Exposes Caddy’s HTTP port via the WireGuard container.

⁠Healthcheck

The container includes a healthcheck script. Docker will automatically restart the container if it becomes unhealthy.

⁠Requirements

• Docker and Docker Compose installed
• Access to /dev/net/tun on the host
• WireGuard configuration files

⁠Updating

To update to the latest version:

docker compose pull
docker compose up -d

⁠FAQ

• Is a web UI or proxy included?
  No. This image is for running WireGuard only. You can add your own reverse proxy or management UI if desired (see Caddy example).

• Can I run this on ARM or Raspberry Pi?
  Yes, multi-architecture builds are supported.

⁠License

MIT

Secure, fast, and minimal WireGuard VPN in Docker.
For questions or issues, open a GitHub issue or discussion.

Happy networking!