Gluetun

The stack

Generated output

services:
  gluetun:
    image: docker.io/qmcgaw/gluetun:v3.41.1@sha256:1a5bf4b4820a879cdf8d93d7ef0d2d963af56670c9ebff8981860b6804ebc8ab
    restart: unless-stopped
    environment:
      VPN_SERVICE_PROVIDER: ${VPN_SERVICE_PROVIDER}
      VPN_TYPE: wireguard
      WIREGUARD_PRIVATE_KEY: ${WIREGUARD_PRIVATE_KEY}
      WIREGUARD_ADDRESSES: ${WIREGUARD_ADDRESSES}
      SERVER_COUNTRIES: ${SERVER_COUNTRIES}
      TZ: ${TZ}
    volumes:
      - gluetun-data:/gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
volumes:
  gluetun-data: {}

# Caddyfile for Gluetun
# Replace gluetun.local with your real domain. Caddy issues TLS automatically.

gluetun.local {
	encode zstd gzip
	reverse_proxy gluetun:8000
}

# Traefik labels for Gluetun
# Merge into the gluetun service in docker-compose.yml.
# Assumes an external Traefik network named "proxy" and a
# certresolver named "letsencrypt". Replace gluetun.local.

services:
  gluetun:
    labels:
      traefik.enable: "true"
      traefik.http.routers.gluetun.rule: Host(`gluetun.local`)
      traefik.http.routers.gluetun.entrypoints: websecure
      traefik.http.routers.gluetun.tls: "true"
      traefik.http.routers.gluetun.tls.certresolver: letsencrypt
      traefik.http.services.gluetun.loadbalancer.server.port: "8000"
    networks:
      - proxy
      - default
networks:
  proxy:
    external: true

Replace gluetun.local with your domain. Generate secrets below.

Environment

.env with generated secrets

# The VPN provider Gluetun should connect to. Must be one of the names Gluetun supports, for example mullvad, protonvpn, ivpn, airvpn, or nordvpn.
VPN_SERVICE_PROVIDER=mullvad

# The WireGuard client private key issued by your VPN provider. This is not generated here — paste the value from the provider WireGuard configuration. Treat it as a credential.
WIREGUARD_PRIVATE_KEY=

# The client address your provider assigns in its WireGuard configuration, in CIDR form. Not a secret, but specific to your account.
WIREGUARD_ADDRESSES=10.64.0.2/32

# Optional. Restrict server selection to one or more countries (comma-separated). Leave it empty to let Gluetun choose. Provider support varies; some use cities or hostnames instead.
SERVER_COUNTRIES=Switzerland

# Timezone for log timestamps (IANA tz name).
TZ=UTC

Requirements

Before you start

• An active subscription with a VPN provider Gluetun supports (Mullvad, ProtonVPN, IVPN, AirVPN, NordVPN, and many more), plus the WireGuard key and address that provider assigns you.
• The `NET_ADMIN` capability for the container — set via `cap_add` in this compose.
• The `/dev/net/tun` device present on the host and passed into the container — also handled in this compose.
• Docker 24+ and Docker Compose v2.

Deploy

How to deploy

1. Generate a WireGuard configuration in your VPN provider dashboard, then copy the private key and the assigned client address.
2. In `.env`, set `VPN_SERVICE_PROVIDER`, paste `WIREGUARD_PRIVATE_KEY` and `WIREGUARD_ADDRESSES`, and optionally pin `SERVER_COUNTRIES`. Do not use the "Generate secrets" button for the key — it must be the real value from your provider.
3. Start the stack: `docker compose up -d`, then watch `docker compose logs -f gluetun` for the line confirming the tunnel is up and reporting the new public IP.
4. Route another container through the tunnel by adding `network_mode: "service:gluetun"` to it in the same compose project, removing its own `networks`, and publishing its ports on the gluetun service instead.
5. Confirm the exit IP from inside the container: `docker compose exec gluetun wget -qO- https://ipinfo.io/ip` should print the VPN address, not your home address.

Errors

Common errors & fixes

Limitations

Honest limitations

• Gluetun is not a web service and has no UI, so the Caddyfile and Traefik output generated on this page do not apply. There is nothing to reverse-proxy, and `gluetun.local` is only a placeholder this template requires.
• The control server on port 8000 is an internal status and management API, not a public endpoint. This stack does not publish it; expose it to localhost only if you need it.
• You need a paid subscription with a supported provider. Gluetun is only the client; it does not provide VPN service itself.
• The WireGuard key and address come from your provider and cannot be generated here, so the "Generate secrets" button does not apply to them.
• Routing other containers through Gluetun ties their network to its lifecycle: when Gluetun restarts, their connectivity drops briefly — which is also exactly what makes it a kill switch.

FAQ

Frequently asked

Related

Related stacks