🌊 qBittorrent
Host: Homelab · Compose:
Homelab/qbittorrent/compose.yaml
Stack name:qbittorrent
1. Overview
A qBittorrent instance with a built-in ProtonVPN WireGuard kill-switch using the hotio/qbittorrent image. The VPN ensures all torrent traffic is routed through ProtonVPN's Sydney servers — if the VPN drops, the container loses internet access (kill-switch). Auto port-forwarding is enabled for better peer connectivity.
2. Architecture & Services
| Service | Image | Port | Role |
|---|---|---|---|
qbittorrent |
ghcr.io/hotio/qbittorrent:release-v5.2.3@sha256:873421ad4814dcc31923be0b7358d3f2c23e858fde8e97d7b6fd28da5c57cfc8 |
9765 |
BitTorrent client with WireGuard VPN |
3. Networking
None configuration.
4. Persistent Storage
| Container | Host Path / Volume | Description |
|---|---|---||
| qbittorrent | /docker/qbittorrent/config | qBittorrent config, including wg0.conf |
| qbittorrent | /nfs/media/Downloads | Download destination (NFS mount) |
5. Environment Variables
| Variable | Service | Description |
|---|---|---|
LIBTORRENT |
qbittorrent |
— |
PGID |
qbittorrent |
— |
PRIVOXY_ENABLED |
qbittorrent |
— |
PUID |
qbittorrent |
— |
TZ |
qbittorrent |
Timezone |
UMASK |
qbittorrent |
— |
UNBOUND_ENABLED |
qbittorrent |
— |
UNBOUND_NAMESERVERS |
qbittorrent |
— |
VPN_AUTO_PORT_FORWARD |
qbittorrent |
Enable ProtonVPN port forwarding |
VPN_CONF |
qbittorrent |
WireGuard config file (place wg0.conf in config dir) |
VPN_ENABLED |
qbittorrent |
Enable WireGuard VPN kill-switch |
VPN_EXPOSE_PORTS_ON_LAN |
qbittorrent |
Allow web UI on LAN |
VPN_HEALTHCHECK_ENABLED |
qbittorrent |
— |
VPN_LAN_LEAK_ENABLED |
qbittorrent |
— |
VPN_LAN_NETWORK |
qbittorrent |
LAN ranges bypassing VPN |
VPN_NAMESERVERS |
qbittorrent |
— |
VPN_PORT_REDIRECTS |
qbittorrent |
— |
VPN_PROVIDER |
qbittorrent |
Provider hint for port-forward integration |
WEBUI_PORTS |
qbittorrent |
Web UI port |
6. Access & Usage
| URL | Description |
|---|---|
http://<host-ip>:9765 |
qBittorrent Web UI |
Default credentials: admin / adminadmin (change immediately after first login).
# Start
docker compose -f Homelab/qbittorrent/compose.yaml up -d
# Check VPN status
docker exec qbittorrent curl -s https://api.ipify.org
# View logs
docker logs qbittorrent -f
7. Maintenance & Backup
# Update
docker compose -f Homelab/qbittorrent/compose.yaml pull
docker compose -f Homelab/qbittorrent/compose.yaml up -d
# Backup config (includes WireGuard key — keep secure!)
rsync -av /docker/qbittorrent/config/ /backup/qbittorrent/
[!CAUTION]
/docker/qbittorrent/config/wg0.confcontains the WireGuard private key for ProtonVPN. Do not commit this to a public repository. Store it in a password manager or secrets vault.