docker.recipes

Gluetun VPN Client

intermediate

VPN client container supporting multiple providers.

Overview

Gluetun is a lightweight VPN client container developed by Quentin McGaw that revolutionizes how containerized applications connect to VPN services. Unlike traditional VPN clients that modify host networking, Gluetun runs as a dedicated container that other Docker services can route their traffic through, providing network isolation and preventing IP leaks. The project emerged from the need to securely connect Docker containers to VPN services without compromising the host system's network configuration. This Gluetun deployment creates a VPN gateway container that establishes encrypted connections to over 50 VPN providers including Mullvad, NordVPN, Private Internet Access, and Surfshark. The container includes built-in kill switch functionality, HTTP proxy server, and Shadowsocks proxy for external clients. Other containers can route all their traffic through Gluetun by simply adding 'network_mode: service:gluetun' to their configuration, ensuring complete traffic encryption without individual VPN client installations. This setup is essential for privacy-conscious users, BitTorrent clients, web scrapers, and any application requiring IP masking or geo-location changes. System administrators benefit from centralized VPN management where multiple services share a single VPN connection, reducing provider costs and simplifying network monitoring. The container-based approach ensures VPN connectivity remains isolated from host networking while providing reliable failover protection.

Key Features

  • Support for 50+ VPN providers with automatic server selection and failover mechanisms
  • Built-in kill switch that blocks all traffic if VPN connection drops, preventing IP leaks
  • HTTP proxy server on port 8888 for web traffic routing and external client connections
  • Shadowsocks proxy on port 8388 for encrypted proxy access from mobile devices and external clients
  • WireGuard and OpenVPN protocol support with automatic configuration generation
  • Network namespace sharing allowing other containers to route traffic through the VPN tunnel
  • Real-time connection monitoring with automatic reconnection and provider server rotation
  • DNS leak protection with configurable DNS servers and IPv6 blocking capabilities

Common Use Cases

  • 1Routing BitTorrent clients through VPN to mask downloading activity and bypass ISP throttling
  • 2Web scraping operations requiring IP rotation and geographic location changes
  • 3Accessing geo-restricted content and services from different countries
  • 4Securing IoT device communications in smart home setups through centralized VPN routing
  • 5Development testing of location-based applications across different regions
  • 6Corporate remote access for containerized applications requiring secure external connections
  • 7Privacy protection for media streaming containers and download managers in home lab environments

Prerequisites

  • Active VPN subscription with a supported provider (Mullvad, NordVPN, PIA, Surfshark, etc.)
  • VPN account credentials or WireGuard private keys from your provider
  • Docker host with NET_ADMIN capability support for container networking modifications
  • Minimum 256MB RAM allocated for the Gluetun container plus provider connection overhead
  • Open firewall ports 8888 and 8388 if accessing proxy services from external networks
  • Understanding of Docker networking concepts for routing other containers through Gluetun

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  gluetun: 
3    image: qmcgaw/gluetun:latest
4    container_name: gluetun
5    restart: unless-stopped
6    cap_add: 
7      - NET_ADMIN
8    environment: 
9      VPN_SERVICE_PROVIDER: ${VPN_PROVIDER}
10      VPN_TYPE: wireguard
11      WIREGUARD_PRIVATE_KEY: ${WG_PRIVATE_KEY}
12      WIREGUARD_ADDRESSES: ${WG_ADDRESSES}
13      SERVER_COUNTRIES: ${SERVER_COUNTRIES}
14    volumes: 
15      - gluetun_data:/gluetun
16    ports: 
17      - "8888:8888/tcp"
18      - "8388:8388/tcp"
19      - "8388:8388/udp"
20
21volumes: 
22  gluetun_data:

.env Template

.env
1VPN_PROVIDER=mullvad
2WG_PRIVATE_KEY=your-private-key
3WG_ADDRESSES=10.x.x.x/32
4SERVER_COUNTRIES=Switzerland

Usage Notes

  1. 1Docs: https://github.com/qdm12/gluetun-wiki
  2. 2Route containers through VPN: network_mode: service:gluetun
  3. 3HTTP proxy on 8888, Shadowsocks on 8388 for external clients
  4. 4Supports 50+ providers: Mullvad, NordVPN, PIA, Surfshark, etc.
  5. 5Check IP: docker exec gluetun wget -qO- ifconfig.me
  6. 6Built-in kill switch prevents traffic leaks if VPN drops

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  gluetun:
5    image: qmcgaw/gluetun:latest
6    container_name: gluetun
7    restart: unless-stopped
8    cap_add:
9      - NET_ADMIN
10    environment:
11      VPN_SERVICE_PROVIDER: ${VPN_PROVIDER}
12      VPN_TYPE: wireguard
13      WIREGUARD_PRIVATE_KEY: ${WG_PRIVATE_KEY}
14      WIREGUARD_ADDRESSES: ${WG_ADDRESSES}
15      SERVER_COUNTRIES: ${SERVER_COUNTRIES}
16    volumes:
17      - gluetun_data:/gluetun
18    ports:
19      - "8888:8888/tcp"
20      - "8388:8388/tcp"
21      - "8388:8388/udp"
22
23volumes:
24  gluetun_data:
25EOF
26
27# 2. Create the .env file
28cat > .env << 'EOF'
29VPN_PROVIDER=mullvad
30WG_PRIVATE_KEY=your-private-key
31WG_ADDRESSES=10.x.x.x/32
32SERVER_COUNTRIES=Switzerland
33EOF
34
35# 3. Start the services
36docker compose up -d
37
38# 4. View logs
39docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/gluetun/run | bash

Troubleshooting

  • VPN connection fails with authentication error: Verify VPN_SERVICE_PROVIDER matches your actual provider name and check credentials in environment variables
  • Other containers lose internet connectivity: Ensure containers using network_mode service:gluetun don't have conflicting port mappings or network configurations
  • DNS resolution fails inside routed containers: Add BLOCK_MALICIOUS=off and DOT=off environment variables to disable DNS filtering
  • Container exits with 'cannot create TUN device' error: Verify Docker daemon runs with --cap-add=NET_ADMIN or add privileged: true to the service
  • HTTP proxy returns 'connection refused' on port 8888: Check if HTTPPROXY environment variable is set to 'on' and container has fully established VPN connection
  • Frequent disconnections and reconnections: Set FIREWALL_VPN_INPUT_PORTS to allow your VPN provider's specific ports and disable IPv6 with VPN_TYPE_IPV6_ENABLED=false

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

gluetun

Tags

#gluetun#vpn#client#privacy

Category

Security & Networking

Related Recipes

Ad Space