Skip to content

qbitwebui — Setup

Multi-instance qBittorrent web manager. Runs as a Docker container on LXC 118 (tools), behind oauth2-proxy on LXC 119 (infra-apps) for PocketID authentication. Manages multiple qBittorrent instances (seedbox, normal) from a single UI.

  • GitHub: https://github.com/Maciejonos/qbitwebui
  • Docs: https://maciejonos.github.io/qbitwebui/

Infrastructure

Host Internal URL
Docker (LXC 118) 192.168.1.118:3002 (via oauth2-proxy on LXC 119) https://qbit.eva-00.network

Observability

Logs

qbitwebui logs are collected via Grafana Alloy Docker discovery and shipped to Loki.

Query Purpose
{container="qbitwebui"} All container output
{container="qbitwebui"} \|= "error" Errors only
{container="oauth2-proxy-qbitwebui"} oauth2-proxy logs

Access: Grafana → Explore → Loki → Enter query

Metrics

qbitwebui does not export Prometheus metrics by default. Use Loki logs to diagnose issues.

IaC

Artifact Path
Playbook ansible/playbooks/tools.yml
Workflow .forgejo/workflows/tools.yml
Compose services/qbitwebui/docker-compose.yml

Authentication

qbitwebui runs in single-user mode (DISABLE_AUTH=true). Authentication is handled entirely by oauth2-proxy + PocketID SSO. No internal login credentials needed.

Secrets

secret/qbitwebui → pocketid_client_id, pocketid_client_secret, cookie_secret, encryption_key

Managed qBittorrent Instances

Instance Host Port Notes
Seedbox 192.168.1.111 8080 VPN-routed via Gluetun
Normal 192.168.1.111 8081 Direct connection

Both qBittorrent instances have internal auth bypassed for qbitwebui and oauth2-proxy IPs (AuthSubnetWhitelist=192.168.1.118/32, 192.168.1.119/32). When adding instances in qbitwebui, use admin / any password — the whitelist means credentials are not checked for connections from LXC 118 (tools) or LXC 119 (infra-apps).

First Deploy

  1. Store secrets in Vault: 
    # Via vault-write workflow:
path: qbitwebui
data: {"encryption_key": "<openssl rand -hex 32>"}

path: homelab-sso
data: {"qbitwebui_cookie_secret": "<openssl rand -base64 32 | head -c 32>"}
patch: true
  2. Update PocketID homelab-sso OIDC client to add callback URLs:
  3. https://qbit.eva-00.network/oauth2/callback
  4. https://qbit.eva-00.network/oauth2/sign_out
  5. Push to main → triggers Deploy qbitwebui workflow
  6. Redeploy Caddy to pick up new Caddyfile entry
  7. In qbitwebui UI: add qBittorrent instances with their host/port/credentials