How torrentsec/qbittorrent-protonvpn-docker works
1. What this repo is
- A small Docker Compose deployment for a single purpose: run qBittorrent with all torrent traffic forced through ProtonVPN WireGuard via Gluetun.
- The repository is mostly infrastructure-as-code plus runtime configuration, not an application codebase.
2. Primary runtime boundary: host vs containers
- The host machine runs Docker Desktop and exposes only the qBittorrent web UI on localhost:8080.
- Everything else is isolated inside containers, with the VPN container acting as the network gateway for the torrent client.
3. Core service chain
- Gluetun establishes the VPN tunnel to ProtonVPN and enforces the kill-switch / routing rules.
- qBittorrent runs behind Gluetun’s network namespace, so its outbound traffic is intended to traverse only the VPN tunnel.
- This is the key architectural dependency: qBittorrent is not a standalone networked service; it depends on the VPN container for connectivity.
4. Traffic flow
- Control traffic: the user connects from the browser to the qBittorrent Web UI on the host’s localhost:8080.
- Data traffic: torrent peer traffic exits qBittorrent through Gluetun and then out through ProtonVPN.
- Verification flow: the README suggests checking ifconfig.me from inside the qBittorrent container to confirm the public IP is the VPN IP, not the host IP.
5. Inbound connectivity and port forwarding
- The setup is designed to use automatic VPN port forwarding to improve torrent peer connectivity.
- The forwarded port is supplied via environment variables and paired with a ProtonVPN API key, implying the VPN layer is responsible for obtaining and publishing the usable inbound port to qBittorrent.
6. Storage/data boundaries
- The stack separates torrent storage into incomplete and completed areas.
- This implies persistent host-mounted volumes for download state and data, so container restarts do not lose active or finished downloads.
- The actual filesystem layout is defined in docker-compose.yml, but the architecture clearly treats download data as durable external storage rather than container-local state.
7. Configuration and secrets
- All sensitive/runtime configuration is moved into a .env file, with .env.example serving as the template.
- Important inputs include:
- WireGuard private key
- preferred ProtonVPN countries/cities
- UID/GID and timezone
- Gluetun admin credentials
- API key and forwarded port for port forwarding
- This is a classic separation of code/config/secrets, with the Compose file reading environment variables at deployment time.
8. Operational behavior
- Containers are expected to run with auto-restart behavior, making the stack resilient to crashes or transient VPN failures.
- The README also mentions Watchtower, so there is likely a third service that periodically updates container images automatically.
- That makes the runtime model: declarative compose startup, then mostly unattended operation with automatic recovery and updates.
9. Security posture
- The architecture is explicitly designed to prevent IP leakage by making the VPN a hard dependency for qBittorrent networking.
- .env is ignored by Git, and the README emphasizes strong credentials for the Gluetun API/admin access.
- The practical trust boundary is: the host should never need to handle torrent traffic directly; it only brokers container ports and storage.
10. External dependencies
- The system depends on:
- Docker / Docker Compose
- ProtonVPN with WireGuard support (Plus or Visionary plan)
- Public ProtonVPN APIs / port forwarding mechanism through Gluetun
- There are no custom backend services or databases; the only external service that materially shapes the architecture is ProtonVPN.
11. What an architecture diagram should show
- A host box with Docker Compose orchestrating three conceptual pieces:
- Gluetun VPN gateway
- qBittorrent client behind that gateway
- Watchtower for image updates
- Draw the browser/host connection only to the Web UI.
- Draw torrent peer traffic flowing from qBittorrent → Gluetun → ProtonVPN → Internet.
- Show persistent host volumes attached to qBittorrent for download state and media files.
Main entry points: docker-compose.yml Compose · README.md Runbook · .env.example Env template
Components 12
Host
Docker Desktop host boundary and local access points.
- Browser · User access point for the Web UI.
- Web UI · qBittorrent interface exposed on localhost:8080.
- Downloads · Host-mounted storage for incomplete and completed torrent data.
- Docker · Container runtime on the host machine.
Compose Stack
Services defined and wired by Docker Compose.
- Gluetun · WireGuard VPN container with kill-switch and port-forwarding behavior.
- qBittorrent · Torrent client running behind the VPN network namespace.
- Watchtower · Automatically refreshes container images.
External
Third-party network and infrastructure dependencies.
- ProtonVPN · External VPN endpoint and port-forwarding source.
- Internet · Torrent peers and wider outbound network.
Config
Deployment inputs and runtime settings.
- Compose · Defines and starts the container stack.
docker-compose.yml - Env template · Template for runtime variables and secrets.
.env.example - Runbook · Explains setup, VPN verification, and operations.
README.md
Connections 15
- Compose → Gluetun: starts · Compose creates the VPN gateway container.
- Compose → qBittorrent: starts · Compose creates the torrent client container.
- Compose → Watchtower: starts · Compose creates the update automation container.
- Docker → Compose: runs · Docker executes the compose deployment.
- Browser → Web UI: opens · User connects to the local Web UI.
- Web UI → qBittorrent: controls · The UI talks to the qBittorrent process.
- qBittorrent → Gluetun: network via · qBittorrent shares Gluetun's network namespace.
- Gluetun → ProtonVPN: tunnels to · Gluetun establishes the VPN connection.
- qBittorrent → Internet: torrent traffic · Peer traffic exits through the VPN path.
- Gluetun → Internet: egress · VPN egress reaches the public internet.
- Downloads → qBittorrent: mounts · Persistent volumes hold download state and media.
- Env template → Compose: templates · Environment variables configure the stack.
- Runbook → Compose: documents · Runbook explains how the deployment is operated.
- Runbook → Web UI: describes · Documents the localhost access point.
- Runbook → ProtonVPN: depends on · Setup assumes ProtonVPN WireGuard support.