🌊 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 |
hotio/qbittorrent:v5.2.1 |
9765 |
BitTorrent client with WireGuard VPN |
3. Networking
No Docker network entries — the container uses NET_ADMIN capabilities and manages its own WireGuard interface (wg0). The LAN subnet (192.168.10.0/24, 192.168.1.0/24) is allowlisted so the web UI remains reachable locally even when VPN is active.
4. Persistent Storage
| Container | Host Path | Description |
|---|---|---|
qbittorrent |
/docker/qbittorrent/config |
qBittorrent config, including wg0.conf |
qbittorrent |
/nfs/media/Downloads |
Download destination (NFS mount) |
5. Environment Variables
| Variable | Value | Description |
|---|---|---|
VPN_ENABLED |
true |
Enable WireGuard VPN kill-switch |
VPN_CONF |
wg0 |
WireGuard config file (place wg0.conf in config dir) |
VPN_PROVIDER |
proton |
Provider hint for port-forward integration |
VPN_LAN_NETWORK |
192.168.10.0/24,192.168.1.0/24 |
LAN ranges bypassing VPN |
VPN_EXPOSE_PORTS_ON_LAN |
9765/tcp |
Allow web UI on LAN |
VPN_AUTO_PORT_FORWARD |
true |
Enable ProtonVPN port forwarding |
PUID / PGID |
1027:100 |
File ownership for downloads |
TZ |
Australia/Sydney |
Timezone |
WEBUI_PORTS |
9765/tcp,9765/udp |
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.