Skip to content

qBittorrent

Step by step instructions for installing qbittorrent as a docker container that will use a VPN connection as its network connection. If the VPN drops or disconnects, the container will stop.

Tip

You can find the source code to all scripts by clicking the euronvault/eScripts link at the top of this wiki.

In addition, we will implement the following program/scripts.

  • inspector: A script that monitors the network health of a container.
  • assign_category: A script that will auto assign a category of an incoming torrent.
  • ip_checker: A script that monitors the current VPN IP of qbittorrent-openvpn container.

Prerequisites

The following applications will need to be installed and configured first.

  • Git: Version control system that will allow us to interact with most open source software.
  • Python3 & PIP: We will need the PIP utility to install python packages.
  • Docker & Docker compose: (1) The platform used for our applications.
  • Portainer: A GUI to manage Docker.
  • Dozzle: (2) This application will allow easy view of container logs.
  • Watchtower: This will monitor, automate and update the docker container image.
  1. 🔥 Tip

    I recommend using Linux Mint’s official repository
    so that docker will auto update with new versions.

    You can also verify Docker Compose is installed by going HERE.
  2. Container Install
    Using Portainer, create a stack with these settings.
    version: "3"
services:
  dozzle:
    container_name: dozzle
    image: amir20/dozzle:latest
    restart: unless-stopped 
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      DOZZLE_FILTER: "status=running"
      DOZZLE_USERNAME: username
      DOZZLE_PASSWORD: password
      TZ: America/Los_Angeles      
    ports:
      - 8892:8080
    open browser to http://localhost:8892

This list contains miscellaneous things we will use for the install.

Folder Structure

We need to create a new folder for this container. You can create folders in file manager or by using the terminal. Every time we create a new container, you will add a folder with the new container name inside the docker folder. This will be used to save application data, logs etc.. This will make it easier to access and will also prevent lost data if the container or docker crashes. We can also use these folders to back up our containers at a later time. Create two container folders called qbittorrent and qbittorrent-openvpn.

Note

In Linux Mint you can get to your home directory by using ~/ in the terminal.
But when using docker we need to use the full folder path /home/<USERNAME>/docker/qbittorrent/

With the qbittorrent(1) root folder created. We can create four other folders we will need to reference during the docker install setup.

  1. /home/<USERNAME>/docker/qbittorrent/

call them:

  • config
  • custom_scripts
  • downloads
  • scripts

With the qbittorrent-openvpn(1) root folder created. We can create two other folders we will need to reference during the docker install setup.

  1. /home/[username]/docker/qbittorrent-openvpn/

call them:

  • data
  • config

Your folder structure should now look like this: 

~/
├─ docker/
   └─ dozzle
   └─ komga
   └─ mylar
   └─ qbittorrent
        └─ config
        └─ custom_scripts
        └─ downloads
        └─ scripts
   └─ qbittorrent-openvpn
        └─ data
        └─ config
   └─ taiga 
   └─ watchtower

Docker

As previously stated we will be creating a stack. Inside that stack will be two containers. One will be the qbittorrent application and the other will be a qbittorrent-openvpn connection container that qbittorrent will use as a network connection. This will ensure that any data qbittorrent use is encrypted by a VPN connection.

Lets get started,

Custom Scripts

Custom Scripts

You can find more detailed info about this on the docs page.

Because we are using a image by linuxserver.io we have the option to customize the image at startup. To do so linuxserver.io provides a way to have the image install an external script. For our purposes this will install the extra filles our pipeline will need to function.

Essentially, every time the container is started, any file inside the /custom_scripts folder we created earlier will get executed.

Step 01.


1. Download or copy/paste the content of extra_packages.sh (1) into the /custom_scripts folder.
 

  1. Note: You can also find more info about the script at the same repo location.

  2. Inside Portainer, click on Stacks on left sidebar then +Add Stack button.

  3. In the name field type qbittorrent and in the Web editor field copy and past the code in docker-compose-qbittorrent.yml file inside thats inside the Here you will find the source code to the docker-compose-qbittorrent.yml file.

Containers

This part just like creating containers for any other application in Portainer. You could also use the CLI if you choose to do so, which is out the scope of this documentation. You can go here for one of many good articles that will highlight basic CLI commands for Docker.

Step 02.


1. Inside Portainer, click on Stacks > + Add stacks
2. In the Name field type qbittorrent
3. Download or copy/paste the content of docker-compose-qbittorrent.yml (1) into the Web editor field.
4. The final step is to scroll down and click on Deploy the stack
 

  1. Note: Make sure to enter your own variables.

You should now be able to open your web browser, type in your host IP address along with the web port you picked. The port used on the docker-compose-qbittorrent.yml documentation is: 8124.

Info

  • The full address for me would be: http://192.168.1.55:8124
  • The default username is: admin
  • The default password is: adminadmin

If you made it this far and are able to successfully log into qbittorrent web ui then you should change the default username and password at Tools > Options > Web UI > Authentication

This will also be the same username and password you will need for assign_category.py

Inspector

Now that we have our qbittorrent docker up and running we need a way to handle if/when the network connectivity stops working for whatever reason.

To recap, container qbittorrent-openvpn is responsible for ALL network related services for the stack. Container qbittorrent gets network access threw qbittorrent-openvpn.

Image title Image title

This set up ensures that qbittorrent container always have a valid VPN connection for all network traffic with no leaks. Sometimes the VPN connection flickers or drops for a random amount of time. If that happens then container qbittorrent-openvpn will attempt to re-establish a new stable VPN connection. After the VPN network has been restored, container qbittorrent will need restarting in order to use the network from qbittorrent-openvpn again.

The inspector script automates this process of monitoring the network for container qbittorrent. If it detects that the container is "unhealthy" due to the network dropping or stopping it will reboot the container until a stable connection has been established.

For inspector install instructions see the repo.

Watchtower

We need a way to update docker images. watchtower solves this for us. Its different ways to configure watchtower and mine is set up to monitor ALL containers and only exclude the ones I choose. Its only a few containers I do not want watchtower to update. Sometimes updating DB containers will crash the database making the container that depends on the DB container useless.

If this happens you will most likely have to roll back to an older version of the database assuming that you have backups, and you should.

For watchtower install instructions see the repo.

Whats Next?

Now that you have a working qbittorrent container running threw a VPN tunnel, you are ready to download torrents. However, I HIGHLY advise you to complete this task list first.

  • Configure qbittorrent WebUI with the correct setting for logs, monitored folders, and category save paths.

    I use glogg to view all my non docker system journalctl logs.

  • Install and configure ip_checker

  • Setting up notifications for your various applications and automation's. I use Pushover however I am actively testing ntfy that is self-hosted on my NAS via Docker.

  • Backing up your Docker containers.

Troubleshooting & Testing

Passwords

Double check all your scripts to make sure you entered the correct username and passwords. Your VPN providers username and password is prob the most important because the qbittorrent-openvpn container wont start without valid credentials. And since the qbittorrentcontainer is dependant on the qbittorrent-openvpn container, it wont either.

Logs

The logs should be the first thing you check to find out what is doing what. Every container will have logs you can view.

Here are the two primary ways you can view container logs.

  • If you installed Dozzle from the Prerequisites section you will be able to see the logs for all your running containers. Just click on the container you want to view from the left hand colum. This is my preferred method as you wont need to do any additional clicking or drilling down in settings to find logs in Portainer.

    The problem with Dozzle is that if your issues is related to a container not starting, then Dozzle wont see the logs. In this situation you will need to use Portainer.
  • To view the logs in Portainer click on the main qbittorrent stack from the list after you select Stacks from the left hand colum.

    In the Containers section you will see your two containers listed.

    The first icon under Quick Actions will take you to the logs for that container. Right click the icon to open in a new tab or window.

    You should now be able to see logs and determine why a container did not start if that was the issue.

Health

You can check the health of a container from Portainer by going to Stacks > qbittorrent > [CONTAINER NAME] > Container heath section. In that section you will be able to see:

The currentstatus

How many times the containerfailedthe health check

This is set as an env variable in docker-compose-qbittorrent.yml

In our case it will show a count ever time the health check is executed and the container does not have a good or valid network connection.

Thelast outputof the web probe check

This is where you will go to see if you test url is valid. You should see raw web HTML data in this section when the link is good. If you can not get a healthy check, this is the first place to look.

VPN

As stated in the Passwords section, most issues are related to invalid credentials. You can check your VPN creds with outside apps and devices. Be aware that some VPN host have a limit on the amount of devices you can have connected or registered.

A healthy VPN connection will look something like this (depending on the host)

qbittorrent-openvpn logs
023-11-28 20:59:32 VERIFY OK: depth=1, CN=Privado
2023-11-28 20:59:32 VERIFY KU OK
2023-11-28 20:59:32 Validating certificate extended key usage
2023-11-28 20:59:32 ++ Certificate has EKU (str) TLS Web Server Authentication, expects TLS Web Server Authentication
2023-11-28 20:59:32 VERIFY EKU OK
2023-11-28 20:59:32 VERIFY OK: depth=0, CN=ams-005.vpn.privado.io
2023-11-28 20:59:33 Outgoing Data Channel: Cipher 'AES-256-GCM' initialized with 256 bit key
2023-11-28 20:59:33 Incoming Data Channel: Cipher 'AES-256-GCM' initialized with 256 bit key
2023-11-28 20:59:33 Control Channel: TLSv1.2, cipher SSLv3 DHE-RSA-AES256-SHA, peer certificate: 4096 bit RSA, signature: RSA-SHA512
2023-11-28 21:59:32 TLS: tls_process: killed expiring key

IP Check

You can also check & verify what IP address the VPN is using. Here is how you do it.


1. Open a terminal on your host machine.
2. Input docker exec -ti qbittorrent-openvpn /bin/bash (1)
This code will allow you to interact with the container in the command line.
3. Next enter curl ifconfig.io

You should now see the current IP address used by the container.
 

  1. Note: If you get a SUDO error go here