# torrentsec/qbittorrent-protonvpn-docker architecture

> Architecture diagram of the GitHub repository torrentsec/qbittorrent-protonvpn-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/torrentsec/qbittorrent-protonvpn-docker
- Repository: https://github.com/torrentsec/qbittorrent-protonvpn-docker

## Overview

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`](https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/docker-compose.yml) (Compose), [`README.md`](https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/README.md) (Runbook), [`.env.example`](https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/.env.example) (Env template)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host"]
  node_browser(("Browser<br/>user client"))
  node_webui["Web UI<br/>host port"]
  node_downloads[("Downloads<br/>persistent storage")]
  node_docker["Docker<br/>runtime"]
end

subgraph group_stack["Compose Stack"]
  node_gluetun["Gluetun<br/>vpn gateway"]
  node_qbittorrent["qBittorrent<br/>torrent client"]
  node_watchtower["Watchtower<br/>updater"]
end

subgraph group_external["External"]
  node_protonvpn{{"ProtonVPN<br/>vpn provider"}}
  node_internet(("Internet<br/>public network"))
end

subgraph group_config["Config"]
  node_compose["Compose<br/>orchestrator<br/>[docker-compose.yml]"]
  node_env_example["Env template<br/>config template<br/>[.env.example]"]
  node_readme["Runbook<br/>docs<br/>[README.md]"]
end

node_compose -->|"starts"| node_gluetun
node_compose -->|"starts"| node_qbittorrent
node_compose -->|"starts"| node_watchtower
node_docker -->|"runs"| node_compose
node_browser -->|"opens"| node_webui
node_webui -->|"controls"| node_qbittorrent
node_qbittorrent -->|"network via"| node_gluetun
node_gluetun -->|"tunnels to"| node_protonvpn
node_qbittorrent -->|"torrent traffic"| node_internet
node_gluetun -->|"egress"| node_internet
node_downloads -->|"mounts"| node_qbittorrent
node_env_example -->|"templates"| node_compose
node_readme -->|"documents"| node_compose
node_readme -->|"describes"| node_webui
node_readme -->|"depends on"| node_protonvpn

click node_compose "https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/docker-compose.yml"
click node_env_example "https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/.env.example"
click node_readme "https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_webui,node_downloads,node_docker toneBlue
class node_gluetun,node_qbittorrent,node_watchtower toneAmber
class node_protonvpn,node_internet toneMint
class node_compose,node_env_example,node_readme toneRose
```

## Components

### Host

Docker Desktop host boundary and local access points.

- **Browser**: user client · User access point for the Web UI.
- **Web UI**: host port · qBittorrent interface exposed on localhost:8080.
- **Downloads**: persistent storage · Host-mounted storage for incomplete and completed torrent data.
- **Docker**: runtime · Container runtime on the host machine.

### Compose Stack

Services defined and wired by Docker Compose.

- **Gluetun**: vpn gateway · WireGuard VPN container with kill-switch and port-forwarding behavior.
- **qBittorrent**: torrent client · Torrent client running behind the VPN network namespace.
- **Watchtower**: updater · Automatically refreshes container images.

### External

Third-party network and infrastructure dependencies.

- **ProtonVPN**: vpn provider · External VPN endpoint and port-forwarding source.
- **Internet**: public network · Torrent peers and wider outbound network.

### Config

Deployment inputs and runtime settings.

- [Compose](https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/docker-compose.yml): orchestrator · Defines and starts the container stack. · `docker-compose.yml`
- [Env template](https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/.env.example): config template · Template for runtime variables and secrets. · `.env.example`
- [Runbook](https://github.com/torrentsec/qbittorrent-protonvpn-docker/blob/main/README.md): docs · Explains setup, VPN verification, and operations. · `README.md`

## Connections

- 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.
