qbitwebui

repository·master·Indexed 20 days ago

A modern web interface built with React, Hono, and Bun for managing multiple qBittorrent instances from a single dashboard. Features include real-time monitoring, Prowlarr integration, RSS management, an experimental cross-seed implementation, and a built-in file browser. Includes a companion net-agent for network diagnostics and external IP verification.

Tokens: 21.4K
Snippets: 83
Records: 110
Agent score: 68%

What's inside qbitwebui

What is the Network Agent and why use it?
master
The Network Agent is a lightweight companion service designed to provide network diagnostics from the perspective of your qBittorrent host. It is particularly useful when qBittorrent is running behind a VPN or on a remote server, as it runs in the same network namespace as qBittorrent. This ensures that all diagnostics (IP checks, speedtests, DNS lookups) reflect exactly what the qBittorrent instance sees.
Key Capabilities:
- VPN Verification: Confirm the external IP matches your VPN provider.
- Speed Testing: Run Ookla speedtests from the actual download location.
- DNS Debugging: View /etc/resolv.conf and check for leaks.
- Connectivity Testing: Execute ping, traceroute, dig, etc., from the host.
https://github.com/mkbula/qbitwebui/blob/master/docs/guide/network-agent/index.md
Authenticate with net-agent endpoints
master
Except for the /health endpoint, all net-agent endpoints require a valid qBittorrent session ID (SID). The agent validates the SID by calling the qBittorrent API. If qBittorrent is configured with IP bypass (authentication disabled), the agent will automatically skip SID validation.
To provide the SID, use one of the following methods:
- Header: X-QBT-SID: <sid>
- Cookie: SID=<sid>
https://github.com/mkbula/qbitwebui/blob/master/net-agent/README.md

Deploy net-agent with Docker Compose

master

To ensure net-agent can perform diagnostics from the same network perspective as qBittorrent, deploy it using Docker's network_mode: "service:qbittorrent". This allows the agent to access qBittorrent via localhost.

services:
  qbittorrent:
    image: linuxserver/qbittorrent
    ports:
      - "8080:8080"
      - "9876:9876"  # net-agent port

  net-agent:
    image: ghcr.io/mac-torreon/qbitwebui-agent:latest
    network_mode: "service:qbittorrent"
    environment:
      - QBT_URL=http://localhost:8080  # qBittorrent is on localhost due to shared network

Deploy Full Stack: qBittorrent, Agent, and qbitwebui

master

This setup deploys the complete ecosystem: qBittorrent for torrenting, net-agent for network diagnostics, and qbitwebui for management.

Key Networking Details:

The net-agent uses network_mode: "service:qbittorrent" to share the qBittorrent network stack.
The net-agent requires QBT_URL set to http://localhost:8080 (since it shares the network stack with qBittorrent).
qbitwebui depends on qbittorrent and can be configured to view downloads via DOWNLOADS_PATH.

services:
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent-config:/config
      - ./downloads:/downloads
    ports:
      - "8080:8080"      # qBittorrent WebUI
      - "6881:6881"      # BitTorrent TCP
      - "6881:6881/udp"  # BitTorrent UDP
      - "9876:9876"      # Network Agent
    restart: unless-stopped

  net-agent:
    image: ghcr.io/mkbula/qbitwebui-agent:latest
    container_name: net-agent
    network_mode: "service:qbittorrent"
    environment:
      - QBT_URL=http://localhost:8080
    depends_on:
      - qbittorrent
    restart: unless-stopped

  qbitwebui:
    image: ghcr.io/mkbula/qbitwebui:latest
    container_name: qbitwebui
    ports:
      - "3000:3000"
    volumes:
      - ./qbitwebui-data:/data
      - ./downloads:/downloads:ro
    environment:
      - ENCRYPTION_KEY=your-32-character-minimum-key-here
      - DOWNLOADS_PATH=/downloads
    depends_on:
      - qbittorrent
    restart: unless-stopped

Set up the Network Agent with a VPN (Gluetun)

master

When using a VPN container like Gluetun, both the qbittorrent and net-agent containers must use network_mode: service:gluetun. Crucially, the ports for both qBittorrent (e.g., 8080) and the Network Agent (9876) must be exposed on the Gluetun container, not the individual service containers.

services:
  gluetun:
    image: qmcgaw/gluetun
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - "8080:8080"
      - "9876:9876"
    volumes:
      - ./gluetun:/gluetun
    environment:
      - VPN_SERVICE_PROVIDER=your-provider
      - VPN_TYPE=wireguard
    healthcheck:
      test: ping -c 1 1.1.1.1 || exit 1
      interval: 20s
      timeout: 10s
      retries: 5
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: service:gluetun
    depends_on:
      gluetun:
        condition: service_healthy
        restart: true
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - ./qbittorrent:/config
      - ./downloads:/downloads
    healthcheck:
      test: ping -c 1 1.1.1.1 || exit 1
      interval: 60s
      retries: 3
      start_period: 20s
      timeout: 10s
    restart: unless-stopped

  net-agent:
    image: ghcr.io/mkbula/qbitwebui-agent:latest
    container_name: net-agent
    network_mode: service:gluetun
    environment:
      - QBT_URL=http://localhost:8080
    depends_on:
      qbittorrent:
        condition: service_healthy
        restart: true
    restart: unless-stopped

Deploy qbitwebui with VPN (Gluetun)

master

Route your qBittorrent traffic through a VPN using Gluetun. In this configuration, both qbittorrent and net-agent use network_mode: "service:gluetun" to ensure all traffic is routed through the VPN container.

Verification: Use the net-agent within the UI to verify your external IP matches your VPN provider's location.

services:
  gluetun:
    image: qmcgaw/gluetun:latest
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=mullvad  # or your provider
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=your-private-key
      - WIREGUARD_ADDRESSES=10.x.x.x/32
      - SERVER_COUNTRIES=Sweden
    ports:
      - "8080:8080"      # qBittorrent WebUI
      - "6881:6881"      # BitTorrent
      - "6881:6881/udp"
      - "9876:9876"      # Network Agent
    restart: unless-stopped

  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent-config:/config
      - ./downloads:/downloads
    depends_on:
      - gluetun
    restart: unless-stopped

  net-agent:
    image: ghcr.io/mkbula/qbitwebui-agent:latest
    container_name: net-agent
    network_mode: "service:gluetun"
    environment:
      - QBT_URL=http://localhost:8080
    depends_on:
      - qbittorrent
    restart: unless-stopped

  qbitwebui:
    image: ghcr.io/mkbula/qbitwebui:latest
    container_name: qbitwebui
    ports:
      - "3000:3000"
    volumes:
      - ./qbitwebui-data:/data
      - ./downloads:/downloads:ro
    environment:
      - ENCRYPTION_KEY=your-32-character-minimum-key-here
      - DOWNLOADS_PATH=/downloads
    depends_on:
      - qbittorrent
    restart: unless-stopped

Configure qbitwebui with File Browser
master
To enable the file browser feature in qbitwebui, you must mount your downloads directory and set the DOWNLOADS_PATH environment variable.
Required Configuration:
- Volume: Mount your downloads path to /downloads inside the container.
- Environment Variable: DOWNLOADS_PATH=/downloads.
```
services:
  qbitwebui:
    image: ghcr.io/mkbula/qbitwebui:latest
    container_name: qbitwebui
    ports:
      - "3000:3000"
    volumes:
      - ./qbitwebui-data:/data
      - /path/to/your/downloads:/downloads:ro
    environment:
      - ENCRYPTION_KEY=your-32-character-minimum-key-here
      - DOWNLOADS_PATH=/downloads
    restart: unless-stopped
```
https://github.com/mkbula/qbitwebui/blob/master/docs/guide/docker.md
Generate an ENCRYPTION_KEY
master
The ENCRYPTION_KEY is used to encrypt stored credentials. You must generate a secure 32-character hex key and provide it via the ENCRYPTION_KEY environment variable.
Warning: Save this key securely. If it is lost, you will be unable to decrypt existing credentials and will need to re-add all qBittorrent instances.
```
openssl rand -hex 32
```
https://github.com/mkbula/qbitwebui/blob/master/docs/guide/getting-started.md
Set up qbitwebui for development
master
To run qbitwebui locally in development mode, you need Bun installed. You must provide an ENCRYPTION_KEY environment variable before starting the development server.
```
export ENCRYPTION_KEY=$(openssl rand -hex 32)

bun install
bun run dev
```
https://github.com/mkbula/qbitwebui/blob/master/README.md
Manage RSS Feeds and Auto-Download Rules
master
The RSS Manager allows for automated torrent acquisition.
RSS Feeds
- Add feeds via URL.
- Organize feeds into folders.
- Manually refresh feeds.
- Use the grab option on individual articles.
Auto-Download Rules
Create rules to automatically download content based on patterns:
- Name Patterns: Supports regex for matching torrent names.
- Filters: Filter by category, episode, or season.
- Targeting: Set a specific target category and save path for matched items.
- Preview: Use the preview feature to see which articles match your rules before they trigger.
https://github.com/mkbula/qbitwebui/blob/master/docs/guide/features.md
Use the Orphan Manager
master
The Orphan Manager helps maintain disk health by identifying problematic torrents.
Detection Criteria
- Torrents with missing files on the local disk.
- Torrents with an unregistered tracker status.
Actions
- Scan: Run a scan across all connected instances simultaneously.
- Bulk Select: Select all detected orphans.
- Delete: Remove orphans, with the option to also delete the associated files.
https://github.com/mkbula/qbitwebui/blob/master/docs/guide/features.md

Deploy qbitwebui using Docker Compose

master

You can use Docker Compose for more manageable deployments. Below are two common configurations.

### Minimal Setup
```yaml
services:
  qbitwebui:
    image: ghcr.io/mkbula/qbitwebui:latest
    container_name: qbitwebui
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
    environment:
      - ENCRYPTION_KEY=generate-a-32-char-key-here
    restart: unless-stopped

With File Browser

To enable the file browser feature, mount your downloads directory and set the DOWNLOADS_PATH environment variable.

services:
  qbitwebui:
    image: ghcr.io/mkbula/qbitwebui:latest
    container_name: qbitwebui
    ports:
      - "3000:3000"
    volumes:
      - ./data:/data
      - /path/to/downloads:/downloads:ro
    environment:
      - ENCRYPTION_KEY=generate-a-32-char-key-here
      - DOWNLOADS_PATH=/downloads
    restart: unless-stopped

qbitwebui

What's inside qbitwebui

RSS Feeds

Auto-Download Rules

Detection Criteria

Actions

With File Browser