Skip to content

Gluetun

Gluetun is a thin, lightweight container written by qdm12 (GitHub link) with Alpine Linux as the base for a minimal install size. It allows for the tunneling of other containers’ traffic through a supported VPN of your choice. This is especially useful for containers that connect to the internet, such as a BitTorrent application.

The goal of this project was to create a secure way to route traffic for some of my internet-facing Docker containers. I discovered the project via a YouTube video and dove right in. I use Proton VPN, a provider that makes it easy to get my sign-in credentails for the OpenVPN and Wireguard protocols.

Gluetun uses the OpenVPN protocol, which works well enough for my homelab purposes. Wireguard is newer and more efficient, often resulting in higher throughputs. OpenVPN is also locked to one server, so when you download your OpenVPN configuration information, you’ll need to pick the best server for you. If your VPN provider supports Wireguard, Gluetun also supports it.

The developer of Gluetun has built a wiki with instructions for each supported VPN provider, which streamlines the installation and setup processes. What I have written here is the workflow I followed for my own installation.


Pre-requisites and preparation

Here’s what you need to get started with Gluetun.

Prerequisites

  • A server, preferably running Debian, Ubuntu, or Alpine.
  • Docker and Docker Compose installed.
  • A text editor installed such as nano or VSCode over SSH.
  • A valid VPN subscription with a supported provider.
    • The following providers are supported: AirVPN, Cyberghost, ExpressVPN, FastestVPN, HideMyAss, IPVanish, IVPN, Mullvad, NordVPN, Perfect Privacy, Privado, Private Internet Access, PrivateVPN, ProtonVPN, PureVPN, SlickVPN, Surfshark, TorGuard, VPNSecure.me, VPNUnlimited, Vyprvpn, WeVPN, Windscribe
  • OpenVPN or Wireguard authentication details.

Preparation

  1. Create a docker folder if you do not have one.
    1. mkdir docker
  2. Create a gluetun folder inside the Docker one you just made.
    1. mkdir docker/gluetun

Installation

Here are the steps you need to get the Gluetun container installed.

  1. Create a folder for the Gluetun container.
    1. In this example, that would be docker/gluetun
  2. Move into that new directory.
    1. cd docker/gluetun
  3. Create a file called docker-compose.yml
  4. Open the docker-compose.yml file in a text editor.
  5. Copy the following contents into it. It is recommended to copy this code first into a blank notepad file to strip any formatting. (Also note the indentation; YAML is very particular about indentation.)
version: "3"
services:
gluetun:
image: qmcgaw/gluetun
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
ports:
- 8888:8888/tcp # HTTP proxy
- 8388:8388/tcp # Shadowsocks
- 8388:8388/udp # Shadowsocks
- 8112:8112 # Deluge (optional)
volumes:
- /home/USERNAME/docker/gluetun:/gluetun
environment:
- VPN_SERVICE_PROVIDER=VPNPROVIDER
- VPN_TYPE=openvpn
# OpenVPN:
- OPENVPN_USER=OPENVPN_USERNAME
- OPENVPN_PASSWORD=OPENVPN_PASSWORD
# Wireguard:
# - WIREGUARD_PRIVATE_KEY=wOEI9rqqbDwnN8/Bpp22sVz48T71vJ4fYmFWujulwUU=
# - WIREGUARD_ADDRESSES=10.64.222.21/32
# Timezone for accurate log times
- TZ=YOURTIMEZONE
  1. You will need to determine which protocol your VPN provider wants you to use. ProtonVPN, for example, uses OpenVPN at time of writing and did not offer a Wireguard configuration.
  2. Exit the text editor.
  1. If you are not following the Deluge VPN instructions, then type the following.
    1. docker-compose up -d
  2. The Gluetun container will download the resources it needs and start.
  3. To tunnel other containers through Gluetun, you will need to add the following line to their network_mode (with the quotes).
    1. "service:gluetun"