qBittorrent & Gluetun for Beginners: A simple guide to get started with a torrent client constrained to a vpn, intended for users who have basic Docker knowledge.

This guide is designed to teach you how to set up qBittorrent to operate through GlueTUN in docker, allowing you better control over what operates over VPN and what does not. This allows you to run both VPN and regular net containers in the same project.

While the following will be generally applicable to docker as a whole, but will primarily be discussing docker-compose methods and use of gui tools like dockge as those are the methods I am personally most familiar with.

Before you start, there are a few things to check. Look at the GlueTUN wiki to see if your provider is supported. If it is, it will make things a whole lot easier. If not, you can still use it but you'll have to set up a bunch of custom settings.

From this point forward, I'm going to assume you have dockge (or another docker GUI) installed or are proficient enough with docker-compose CLI that you can run a stack from a compose file yourself.

Also, in case you are reading this guide and are newer to docker, it can be useful to make a limited-permission docker user for additional security. I've done this personally using DrFrankenstein's guide for synology devices and there are guides from docker on doing it on a real operating system.

Additionally, before you start you'll probably also want to set up a few directories:

/docker/projects/vpnproject-compose

/docker/gluetun

/docker/qbittorrent

Step 1: Your docker-compose

Dockge Console

In dockge, click the +compose in the top left, if using other methods this will be your docker-compose.yml. After you've made the directory for your docker project, you'll need to set up what your containers are and some important environment variables for each of them. Here I'll paste an example template and then explain what we're doing in it below.

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN #Gives gluetun the necessary permissions to manage VPN connections
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - 8080:8080 # port for qbittorrent
      - XXXX:XXXX # port for qbit port forward if your VPN supports this
    volumes:
      - /docker/gluetun:/gluetun
    environment:
      - PUID=1000 # Set this to your restricted docker user ID and group ID, otherwise ignore these environment variables
      - PGID=1000
      - VPN_SERVICE_PROVIDER=airvpn
      - VPN_TYPE=wireguard
      - SERVER_COUNTRIES=CountryChoice
      - WIREGUARD_PUBLIC_KEY= XXXXXXXXXXXXXXXXXXXXXXXX
      - WIREGUARD_PRIVATE_KEY= XXXXXXXXXXXXXXXXXXXXXXX
      - WIREGUARD_PRESHARED_KEY= XXXXXXXXXXXXXXXXXXXXX
      - WIREGUARD_ADDRESSES=XXXXXXXXXXXXXXXXXXXX
      - WIREGUARD_DNS_ADDRESS=XXXXXXXXXXXXXX
      - UPDATER_PERIOD=24h
      - TZ=Your/Tz



  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Your/TZ
      - WEBUI_PORT=8080
    volumes:
      - /docker/qbittorrent/config:/config
      - /your/torrent/directory:/data/torrents
    network_mode: service:gluetun # run on the vpn network
    depends_on:
      gluetun:
        condition: service_healthy
    restart: unless-stopped

What did we do here?

We create two services (or containers): one called gluetun, one called qbittorrent.

"image" is the URL of the docker image docker is going to be pulling from. After the colon you can put a specific version, but I typically prefer to pull the latest updated image as shown above.
"container_name" is pretty self explanatory, it decides what the name of the container you are creating with this image will be.

In the GlueTUN container specifically, we have a few important lines:

"cap_add" is used in this instance to give the GlueTUN instance the ability to manage VPN connections.
"devices" makes sure the GlueTUN container can access the "tun" network device by mapping its location to the container. If you try this and are still seeing errors regarding /dev/net/tun or something along those lines, you may not have the "tun" kernel module installed on your system. A few ways to fix this can be found here.
"ports" maps public ports from your VPN (which we are sorting of pretending is a router) to local ports in your GlueTUN "machine". The ports on the left side of the colon are the public port to be mapped from, the right side of the colon is the port the local service is expecting. For example, if you have a container that needs to be receiving something on port 80 but you would rather have that mapped to port 1080 or something, you would put a line like "-8080:8080". In the example above, I've included port mappings for the default qbittorrent webUI port, and then an optional line to include if you use a VPN that supports port forwarding.
"volumes" maps real file mappings on your system to "fake" directories that are accessible within the docker container.

Next are the environment variables. These are variables that can be set up for the container in advance, either to enable optional features or to provide variables like logins that are necessary for the service to work. The first two, PUID and GUID are only necessary if you have set up a limited permissions docker user as described in the introduction, otherwise they can be ignored.

For the rest of the gluetun environment variables, it varies from VPN provider to provider. In my example case I've included the variables necessary for AirVPN, but you'll want to follow the guide for your VPN on the gluetun wiki providers page.

"restart: unless-stopped" this tells docker to restart the service if it crashes or stops working unless you manually stop it.

Under the qBittorrent container there are a few arguments we haven't talked about yet. These are:

"TZ" Using the tz database, CTRL+F your city/town or a city/town in the same time zone as you and input it. This gives your logs and error messages times that will make sense to you and is a required environment variable.
"WEBUI_PORT" feels self-explanatory, but just for the sake of completeness: this sets the port used to access the qbittorrent webui

The set of volumes, again, are mapping where your config files will be saved on your real filesystem and where your torrents will be stored in your real filesystem.

"network_mode service:gluetun" ensures your qbittorrent runs on the VPN network

    depends_on:
    gluetun:
    condition: service_healthy

This means that the qbittorrent client won't start until the gluetun service has initialized and is reporting a "healthy" status. If your gluetun doesn't launch and connect properly, qbit won't even turn on.

Step 2: Port Forwarding

While optional, if you are using any private trackers or just like giving back to the torrenting community, it is important to port forward. Essentially, if you are not port forwarded, to connect to any other user that is not port forwarded, you have to go through a peer who is. If you yourself are port forwarded, then you can connect to just about anybody and that makes it far easier to let people leech from you and get that ratio up.

For VPNs that give you static ports like AirVPN, setting up port forwarding is relatively simple and you just need to follow the steps outline on gluetun's VPN port forwarding page and your VPN provider page on the gluetun wiki. For VPNs that assign you random ports and rotate your ports like ProtonVPN, there is an additional environment variable you can add that will update qbittorrent's settings automatically when gluetun detects the port change. To do this, under your gluetun service's environment variables, add these lines:

- VPN_PORT_FORWARDING_UP_COMMAND: |

        /bin/sh -c '

          wget -O- --retry-connrefused --post-data "json={\"listen_port\":{{PORTS}}}" http://127.0.0.1:8080/api/v2/app/setPreferences 2>&1

What this does is updates your webUI when the port updates in gluetun, saving you a lot of headache every time they rotate your port.

Step 3: Checking to ensure the setup is working

A good first step is to go into the gluetun container logs, in my case by using my synology gui but in your case likely dockge or some other portainer replacement. If gluetun is starting up properly, you should see something along the lines of this:

The IP address at the very top after "Public IP address is" should be the public address of the VPN server you are connected to.

Another step I like to take that is maybe redundant is to open the qbittorrent webUI, and then Options --> Advanced and set the "Network Interface" to "tun0". Depending on your network configuration it may be a different number, but you want it to be bound to your gluetun network interface.

While you're in the qbittorrent settings, make sure torrents you add are going to be downloaded to your intended directory. In my example compose file above, I've set our /your/torrent/directory real filesystem directory to be mapped to /data/torrents in the qbittorrent container. Because we've done that, we can set our Default Save Path to "/data/torrents"

Now, to test if our connections for qbittorrent are going through the VPN connection properly. My personal preferred tool for this is ipleak.net, which has a section called Torrent Address Detection. After you click "Activate", it will give you a magnet link to add to your qbittorrent client. Once your torrent says downloading metadata, come back to the ipleak page and see what data it gives you. Ideally, you will be seeing the country and IP of your VPN and not your actual country or IP.

Now there's nothing left to do but enjoy torrenting with better control over your connection, happy seeding! Also, if you have any questions feel free to try me at cenotaph.contact@pm.me

#technical_guide #torrenting #docker

last updated: 2025-07-08