docs-public/projects/gluetun/index.md

title, description, showHero, author, date, lastmod, tags

title	description	showHero	author	date	lastmod	tags
Gluetun	VPN client in a Docker container	false	wompmacho	2026-04-27	2026-04-27	vpn gluetun networking self-hosted

What is Gluetun?

Gluetun is a lightweight Swiss-army-knife Docker container to connect to VPN servers. I use it as a central VPN gateway for other containers like qBittorrent and Nicotine. By routing other containers through Gluetun, they share its VPN connection and benefit from its killswitch, ensuring no traffic leaks if the VPN drops.

Docker Compose Example

{{% include "/srv/configs/docker_compose/gluetun/docker-compose.yaml" %}}

Utilizing Ports in Docker Compose

When using Gluetun as a network stack for other containers (via network_mode: "container:gluetun"), all port mappings must be defined in the Gluetun service itself, not in the service being routed.

Why define ports in Gluetun?

Containers sharing Gluetun's network namespace effectively share its "localhost." Since the routed container has no network stack of its own, Docker cannot map ports directly to it. Gluetun must listen on those ports and pass the traffic through to the shared network namespace.

How to add a new port:

1. Define the mapping in Gluetun: Add the desired port to the ports section of the gluetun service.

   services:
     gluetun:
       ports:
         - '8080:8080' # Example: Web UI for a routed app
   

2. Use Variables: It is recommended to use variables in a .env file for cleaner management, as seen in my setup:

   ports:
     - '${TORRENT_WEBUI_PORT}'
   

3. No ports in routed containers: Ensure the container using network_mode: "container:gluetun" does not have a ports section, as it will cause an error or be ignored.

Local Network Access (Firewall)

By default, Gluetun's killswitch might block access to the container's Web UI from your local network. To fix this, you must define your local subnet in the environment:

environment:
  - FIREWALL_OUTBOUND_SUBNETS=10.0.0.0/24 # Adjust to match your LAN

This allows traffic from your local network to bypass the VPN tunnel, enabling you to access Web interfaces (like qBittorrent) while the VPN is active.

Routing other containers

To route a container through Gluetun, add the following to its docker-compose.yaml:

services:
  my-app:
    network_mode: "container:gluetun"