Gluetun and Transmission Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Gluetun and Transmission Setup Guide

Introduction

Gluetun is a VPN client in a container. Other containers can share its network, so all their traffic goes through the VPN, and if the VPN drops, Gluetun's firewall blocks them instead of leaking your home IP.

In this repository Transmission (BitTorrent) and Soulseek run inside Gluetun's network. Together they replace the older all-in-one transmission-openvpn image (see Transmission-OpenVPN Setup Guide).

Why switch from transmission-openvpn?

  • transmission-openvpn exits whenever OpenVPN loses contact. Docker restarts it, and every restart cuts the network of any container sharing it (Soulseek) until that container is recreated by hand. Its health check could still report Healthy while offline.
  • Gluetun reconnects inside the container without exiting, so the shared network stays up.
  • One VPN connection serves both apps, which uses one device slot with your VPN provider.

Step 1: Gluetun

compose/server1/gluetun.yaml (example uses Private Internet Access; Gluetun supports most providers):

services:
  gluetun:
    container_name: gluetun.${HOST_NAME}
    image: qmcgaw/gluetun:v3
    cap_add: [NET_ADMIN]
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      TZ: ${TZ}
      VPN_SERVICE_PROVIDER: private internet access
      VPN_TYPE: openvpn
      OPENVPN_USER: ${VPN_USER}
      OPENVPN_PASSWORD: ${VPN_PASS}
      SERVER_REGIONS: US East
      VPN_PORT_FORWARDING: "off"
      UPDATER_PERIOD: 24h          # refresh the server list daily
    volumes:
      - ${DOCKERDIR}/gluetun:/gluetun
    ports:
      - "9091:9091"                # Transmission web UI
      - "${SOULSEEK_PORT}:5030"    # Soulseek web UI
    networks:
      mediaserver:
        aliases:
          - transmission
          - transmission-openvpn  # old name, so Sonarr/Radarr/Homepage need no changes
    restart: always
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Key points:

  • Ports for the apps are published on Gluetun, not on the apps.
  • Network aliases keep old hostnames working for anything that already points at them.
  • Pick the region by testing. Speeds vary a lot between regions, and OpenVPN encryption is CPU-heavy on a NAS (one core can cap it around 60-70 MB/s). Try a few regions and keep the fastest.

Step 2: Transmission inside Gluetun

compose/server1/transmission.yaml:

services:
  transmission:
    container_name: transmission.${HOST_NAME}
    image: lscr.io/linuxserver/transmission:latest
    network_mode: "service:gluetun"
    depends_on:
      gluetun:
        condition: service_healthy
    environment:
      PUID: ${PUID}
      PGID: ${PGID}
      TZ: ${TZ}
      USER: ${TRANS_USER}
      PASS: ${TRANS_PASS}
    volumes:
      - ${DOCKERDIR}/transmission/config:/config
      - ${USERDOWNLOAD}/Torrents:/downloads
    restart: always

network_mode: "service:gluetun" means Transmission has no network of its own. Soulseek is set up the same way.

Settings live in appdata/transmission/config/settings.json. This image doesn't read TRANSMISSION_* environment variables like the old one did. Typical values: download-dir /downloads/Completed, incomplete-dir /downloads/Incomplete, watch-dir /downloads, encryption 1, peer-limit-global 240, umask 2. Stop the container before editing, or Transmission overwrites the file on exit.

Moving from transmission-openvpn: copy transmission-home (settings, torrents/, resume/) from the old config folder into the new one and keep the same /downloads mount, so the torrent list and Sonarr/Radarr paths still match.

Step 3: Start Everything

docker compose -p mediaserver -f docker-compose-server1.yaml up -d gluetun transmission soulseek
docker logs gluetun.<host> | grep "Public IP address"

The public IP shown should be the VPN's, not yours. Check from inside Transmission too:

docker exec transmission.<host> curl -s https://icanhazip.com

Updating (Read This)

Watchtower is off for Gluetun on purpose. Recreating Gluetun leaves Transmission and Soulseek attached to a network that no longer exists. Update all three together, by hand:

docker compose -p mediaserver -f docker-compose-server1.yaml pull gluetun
docker compose -p mediaserver -f docker-compose-server1.yaml up -d gluetun transmission soulseek

If Gluetun ever restarts on its own, recreate the apps:

docker compose -p mediaserver -f docker-compose-server1.yaml up -d --force-recreate --no-deps transmission soulseek

Troubleshooting

  • TLS key negotiation failed / no server answers: the built-in server list is stale for your region. Refresh it, then restart Gluetun:
    docker run --rm -v /path/to/appdata/gluetun:/gluetun qmcgaw/gluetun:v3 update -enduser -providers "private internet access"
  • The VPN drops when you test another VPN container: don't run a second connection to the same provider region at the same time; it can knock the live one off.
  • Transmission's web UI won't load: it's published on Gluetun's ports, so check Gluetun is healthy first, then recreate Transmission.
  • Port forwarding: possible with PIA, but Transmission's peer port must be updated on every reconnect, which needs extra scripting. It's off here.
⚠️ **GitHub.com Fallback** ⚠️