hbixu/qbittorrent-wireguard-proxy
Docker image running qBittorrent (nox) over WireGuard VPN, with optional SOCKS5/HTTP proxies.
Image
Networking
0
1.7K
hbixu/qbittorrent-wireguard-proxy repository overview
qBittorrent WireGuard Proxy
Docker image that runs qBittorrent (nox) over a WireGuard VPN tunnel so BitTorrent traffic is forced through the VPN. Includes SOCKS5 and HTTP/HTTPS proxies so other apps can use the same VPN.
Features
- WireGuard VPN with automatic monitoring and restart
- qBittorrent (nox) with Web UI, traffic bound to VPN
- SOCKS5 proxy (TCP/UDP) and HTTP/HTTPS proxy (tinyproxy)
- Proxies and qBittorrent start/stop with VPN (PostUp/PostDown hooks)
- Based on LinuxServer.io baseimage-alpine
Image versions
| Image tag | Base image | WireGuard (tools / go) | tinyproxy | go-socks5-proxy | qBittorrent |
|---|---|---|---|---|---|
1.1.0 | 3.23-48fea208-ls9 | 1.0.20250521-r1 / 0.0.20250522-r6 | 1.11.2-r0 | 1.0.0 | 5.1.4-r2 |
1.0.0 | 3.23-d34fa4d2-ls4 | 1.0.20250521-r1 / 0.0.20250522-r5 | 1.11.2-r0 | 1.0.0 | 5.1.4-r2 |
Requirements
- WireGuard configuration file (
.conf) withPostUp/PostDownhooks (see GitHub for example) - Host:
NET_ADMIN,/dev/net/tun, kernel 5.6+ or wireguard-go
Quick start
# Pull image
docker pull hbixu/qbittorrent-wireguard-proxy:latest
# Create directories and add your WireGuard .conf
mkdir -p configs-wireguard configs-tinyproxy configs-qbittorrent downloads logs
# Copy your wg0.conf (or your filename) into configs-wireguard/
# Run with docker-compose (see example below) or:
docker run -d --cap-add=NET_ADMIN --cap-add=SYS_MODULE --device /dev/net/tun \
-v $(pwd)/configs-wireguard:/config/wireguard:ro \
-v $(pwd)/configs-qbittorrent:/config/qbittorrent \
-v $(pwd)/downloads:/downloads \
-v $(pwd)/logs:/var/log \
-e VPN_CONFIG_FILE=wg0.conf \
-p 1080:1080 -p 8080:8080 -p 8081:8081 -p 6881:6881 -p 6881:6881/udp \
hbixu/qbittorrent-wireguard-proxy:latest
Environment variables
| Variable | Required | Description |
|---|---|---|
VPN_CONFIG_FILE | Yes | WireGuard config filename inside /config/wireguard/ (e.g. wg0.conf) |
TZ | No | Timezone (default: Europe/Lisbon) |
PUID / PGID | No | File ownership for logs/configs (default: 1000) |
TINYPROXY_USER / TINYPROXY_GROUP | No | User/group for tinyproxy (default: nobody). Override only if needed. |
LOG_ROTATE_DAYS | No | Days to keep rotated logs (default: 7) |
VPN_ENABLED | No | Set to false to run proxy without VPN (default: true) |
VPN_CHECK_INTERVAL | No | VPN check interval in seconds (default: 5) |
VPN_CHECK_HOST | No | Host used to check VPN connectivity (default: 8.8.8.8) |
PROXY_SOCKS5_PORT | No | SOCKS5 port (default: 1080) |
PROXY_HTTP_PORT | No | HTTP proxy port (default: 8080) |
PROXY_SOCKS5_ENABLED / PROXY_HTTP_ENABLED | No | Enable/disable proxies (default: true) |
PROXY_ALLOWED_NETWORKS | No | Allowed networks for both proxies, space-separated (default: 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16) |
QBITTORRENT_ENABLED | No | Enable/disable qBittorrent (default: true) |
QBITTORRENT_WEBUI_PORT | No | Web UI port (default: 8081) — must match host port mapping for CSRF |
QBITTORRENT_LISTEN_PORT | No | BitTorrent listen port (default: 6881) |
QBITTORRENT_CONFIG_READONLY | No | If true, do not modify qBittorrent.conf (user-managed) (default: false) |
HEALTHCHECK_DEBUG | No | Enable debug output in healthcheck logs (default: false) |
Full list and details: see GitHub repository.
Example docker-compose
Full docker-compose.yml with all options: see GitHub.
services:
wireguard-proxy:
image: hbixu/qbittorrent-wireguard-proxy:latest
container_name: qbittorrent-wireguard-proxy
cap_add:
- NET_ADMIN
- SYS_MODULE
devices:
- /dev/net/tun
volumes:
- ./configs-wireguard:/config/wireguard:ro
- ./configs-tinyproxy:/config/tinyproxy
- ./configs-qbittorrent:/config/qbittorrent
- ./downloads:/downloads
- ./logs:/var/log
environment:
- VPN_CONFIG_FILE=wg0.conf
- TZ=Europe/Lisbon
- PUID=1000
- PGID=1000
- VPN_ENABLED=true
ports:
- "1080:1080" # SOCKS5
- "8080:8080" # HTTP proxy
- "8081:8081" # qBittorrent Web UI
- "6881:6881" # BitTorrent TCP
- "6881:6881/udp" # BitTorrent UDP
restart: unless-stopped
healthcheck:
test: ["CMD", "/root/healthcheck.sh"]
interval: 30s
timeout: 10s
start_period: 60s
retries: 3
Ports
| Port | Service |
|---|---|
| 1080 | SOCKS5 proxy |
| 8080 | HTTP/HTTPS proxy |
| 8081 | qBittorrent Web UI |
| 6881 | BitTorrent (TCP/UDP) |
Security note
WireGuard runs as root (required). When PUID/PGID are set, go-socks5-proxy and qBittorrent run as non-root. See the GitHub repo for full security and permission details.
Links
- Source / full documentation: GitHub
- Report issues: GitHub Issues
- License: GPL-3.0 (see repository)
Tag summary
Content type
Image
Digest
sha256:88866b617…
Size
158.3 MB
Last updated
5 months ago
docker pull hbixu/qbittorrent-wireguard-proxy