A ZimaOS user wanted qBittorrent and an ARR stack to route through ProtonVPN with Gluetun, but Gluetun appeared greyed out and had no normal Web UI. The thread offered two architectures: a qBittorrent image with integrated VPN support, or a separate Gluetun container that owns the network namespace.
Gluetun is primarily a VPN gateway container. A grey app tile does not by itself prove failure, and its control server is not the same thing as a conventional application dashboard.
Put qBittorrent Inside Gluetun’s Network Namespace
For the separate-container pattern, qBittorrent uses:
network_mode: "service:gluetun"Because qBittorrent then shares Gluetun’s network stack, publish the qBittorrent Web UI and torrent ports on the Gluetun service, not on qBittorrent:
services:
gluetun:
ports:
- "9080:9080/tcp"
qbittorrent:
network_mode: "service:gluetun"Adapt the port to the qBittorrent image’s documented Web UI setting. Do not copy the thread’s complete Compose sample without review: it contains spelling and network-name inconsistencies that can prevent deployment.
Generate ProtonVPN Credentials for the Chosen Protocol
Use Proton VPN’s WireGuard configuration guide rather than a normal account password. Store the private key as a secret or protected environment value and never paste it into screenshots, forum posts, or a public Compose repository.
The current Gluetun ProtonVPN provider documentation is authoritative for variable names. Current releases use VPN_PORT_FORWARDING=on when Proton port forwarding is required.
VPN Port Forwarding Is Not Docker Port Mapping
Docker mapping exposes a local service from the container to your LAN. Proton’s forwarded port is assigned on the VPN server for incoming peer traffic. Gluetun’s VPN port-forwarding guide explicitly separates these concepts.
For Proton WireGuard, enable NAT-PMP when generating the configuration and select a P2P/port-forwarding-capable server. Proton assigns a random forwarded port; qBittorrent may need automation so its listening port tracks that value.
Keep Secrets Out of the Main Compose File
The community example created separate env/ and secrets/ folders for the WireGuard private key and qBittorrent credentials. That is safer than committing them inline, but filesystem permissions and backups still matter. A Docker secret file is plain text on the host before Docker mounts it.
Verify the Tunnel Before Starting Downloads
- Start Gluetun and read its logs for a successful VPN connection.
- Confirm its health check passes.
- Start qBittorrent in the Gluetun namespace.
- Open the Web UI through the host port published on Gluetun.
- Check the public IP from inside the shared namespace.
- Stop Gluetun and confirm qBittorrent loses internet access before trusting the kill-switch behavior.
An Integrated VPN Image Is a Different Tradeoff
The thread suggested Hotio’s qBittorrent Proton documentation as an alternative that can remove the separate Gluetun service. That can simplify the stack, but it changes the image, environment variables, update path, and support source. Choose one architecture rather than combining both.
Gluetun and qBittorrent FAQ
Why is the Gluetun tile not opening like an app?
Gluetun is a gateway container; its optional control server is not a normal qBittorrent-style Web UI.
Where should qBittorrent’s Web UI port be published?
On Gluetun when qBittorrent uses network_mode: service:gluetun.
Should the thread’s full Compose file be pasted unchanged?
No. It contains likely typos and must be rebuilt against current Gluetun, qBittorrent, and Proton documentation.
