Skip to content

qbit-guard logo Configuration Examples

This page provides working examples of qbit-guard configurations for different deployment scenarios and use cases.

Example Usage

All examples include complete Docker Compose configurations. Adapt environment variables to match your setup.

🐳 Docker Compose Examples

Basic configuration for getting started quickly

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
version: '3.8'

services:
  qbit-guard:
    image: ghcr.io/gengines/qbit-guard:latest
    container_name: qbit-guard
    restart: unless-stopped
    environment:
      # Essential qBittorrent connection
      - QBIT_HOST=http://qbittorrent:8080
      - QBIT_USER=admin
      - QBIT_PASS=your_password_here
      - QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr

      # Pre-air checking with Sonarr
      - ENABLE_PREAIR_CHECK=1
      - SONARR_URL=http://sonarr:8989
      - SONARR_APIKEY=your_sonarr_api_key_here

      # Pre-air checking with Radarr (for movies)
      - ENABLE_PREAIR_CHECK=1
      - RADARR_URL=http://radarr:7878
      - RADARR_APIKEY=your_radarr_api_key_here
      - TMDB_APIKEY=your_tmdb_api_key_here  # Optional: Enhanced movie release date accuracy

      # ISO cleanup
      - ENABLE_ISO_CHECK=1

      - LOG_LEVEL=INFO
    networks: [arr-network]

networks:
  arr-network: { driver: bridge }

Getting Started

This minimal setup enables pre-air checking for both TV shows and movies, plus ISO cleanup. Perfect for testing qbit-guard functionality.

Production-ready setup with all features enabled

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
version: '3.8'

services:
  qbit-guard:
    image: ghcr.io/gengines/qbit-guard:latest
    container_name: qbit-guard
    restart: unless-stopped
    environment:
      # qBittorrent connection
      - QBIT_HOST=http://qbittorrent:8080
      - QBIT_USER=admin
      - QBIT_PASS=your_password_here
      - QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr
      - QBIT_DELETE_FILES=true

      # Pre-air checking with Sonarr
      - ENABLE_PREAIR_CHECK=1
      - SONARR_URL=http://sonarr:8989
      - SONARR_APIKEY=your_sonarr_api_key_here
      - SONARR_CATEGORIES=tv-sonarr
      - EARLY_GRACE_HOURS=6
      - EARLY_HARD_LIMIT_HOURS=72
      - EARLY_WHITELIST_GROUPS=SCENE,P2P,WEB
      - WHITELIST_OVERRIDES_HARD_LIMIT=1

      # Pre-air checking with Radarr (for movies)
      - ENABLE_PREAIR_CHECK=1
      - RADARR_URL=http://radarr:7878
      - RADARR_APIKEY=your_radarr_api_key_here
      - RADARR_PREAIR_CATEGORIES=radarr
      - TMDB_APIKEY=your_tmdb_api_key_here  # Enhanced movie release date accuracy

      # Internet cross-verification
      - INTERNET_CHECK_PROVIDER=both
      - TVDB_APIKEY=your_tvdb_api_key_here

      # ISO/BDMV cleanup
      - ENABLE_ISO_CHECK=1
      - MIN_KEEPABLE_VIDEO_MB=100

      # Radarr integration for blocklisting
      - RADARR_URL=http://radarr:7878
      - RADARR_APIKEY=your_radarr_api_key_here

      # Performance tuning
      - WATCH_POLL_SECONDS=3.0
      - METADATA_MAX_WAIT_SEC=300
      - METADATA_DOWNLOAD_BUDGET_BYTES=104857600  # 100MB

      # Extension filtering
      - GUARD_EXT_STRATEGY=allow
      - GUARD_ALLOWED_EXTS=mkv,mp4,m4v,avi,ts,m2ts,mov,webm,srt,ass

      - LOG_LEVEL=INFO
    networks: [arr-network]

networks:
  arr-network: { driver: bridge }

Production Ready

This configuration includes all features: TV and movie pre-air checking, internet verification, ISO cleanup, and extension filtering.

Optimized for fast processing and high throughput

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
version: '3.8'

services:
  qbit-guard:
    image: ghcr.io/gengines/qbit-guard:latest
    container_name: qbit-guard
    restart: unless-stopped
    environment:
      - QBIT_HOST=http://qbittorrent:8080
      - QBIT_USER=admin
      - QBIT_PASS=your_password_here
      - QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr

      # Fast polling and processing
      - WATCH_POLL_SECONDS=1.0
      - WATCH_PROCESS_EXISTING_AT_START=1

      # Aggressive timeouts for faster failure detection
      - SONARR_TIMEOUT_SEC=90
      - RADARR_TIMEOUT_SEC=90
      - TVMAZE_TIMEOUT_SEC=15
      - TVDB_TIMEOUT_SEC=15

      # More retries for reliability
      - SONARR_RETRIES=5
      - RADARR_RETRIES=5

      # Quick metadata fetching
      - METADATA_MAX_WAIT_SEC=60
      - METADATA_DOWNLOAD_BUDGET_BYTES=52428800  # 50MB

      # Enable all checks
      - ENABLE_PREAIR_CHECK=1
      - ENABLE_ISO_CHECK=1
      - SONARR_URL=http://sonarr:8989
      - SONARR_APIKEY=your_sonarr_api_key_here
      - RADARR_URL=http://radarr:7878
      - RADARR_APIKEY=your_radarr_api_key_here
      - TMDB_APIKEY=your_tmdb_api_key_here  # Optional: Enhanced movie release date accuracy

      - LOG_LEVEL=INFO
    networks: [arr-network]
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.5'

networks:
  arr-network: { driver: bridge }

Resource Usage

High-performance settings will use more CPU and network resources. Monitor system performance.

⚙ Use Case Examples

Configuration focused on Sonarr integration

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
environment:
  - QBIT_HOST=http://qbittorrent:8080
  - QBIT_USER=admin
  - QBIT_PASS=your_password_here
  - QBIT_ALLOWED_CATEGORIES=tv-sonarr

  # Pre-air checking for TV shows
  - ENABLE_PREAIR_CHECK=1
  - SONARR_URL=http://sonarr:8989
  - SONARR_APIKEY=your_sonarr_api_key_here
  - EARLY_GRACE_HOURS=6
  - EARLY_HARD_LIMIT_HOURS=72

  # Internet verification for better accuracy
  - INTERNET_CHECK_PROVIDER=tvmaze

  # Disable ISO check (not needed for TV shows)
  - ENABLE_ISO_CHECK=0

  - LOG_LEVEL=INFO

TV-Focused

This configuration focuses on TV show management with Sonarr integration and pre-air checking.

Configuration focused on Radarr integration

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
environment:
  - QBIT_HOST=http://qbittorrent:8080
  - QBIT_USER=admin
  - QBIT_PASS=your_password_here
  - QBIT_ALLOWED_CATEGORIES=radarr

  # Movie pre-air checking with Radarr and TMDB
  - ENABLE_PREAIR_CHECK=1
  - RADARR_URL=http://radarr:7878
  - RADARR_APIKEY=your_radarr_api_key_here
  - RADARR_PREAIR_CATEGORIES=radarr
  - TMDB_APIKEY=your_tmdb_api_key_here  # Primary source for movie release dates
  - EARLY_GRACE_HOURS=6
  - EARLY_HARD_LIMIT_HOURS=72

  # Disable Sonarr integration (movies only)
  # ENABLE_PREAIR_CHECK=1 still applies to movies via Radarr categories

  # Enable ISO cleanup for movie disc images
  - ENABLE_ISO_CHECK=1
  - MIN_KEEPABLE_VIDEO_MB=100

  # Strict extension filtering for movies
  - GUARD_EXT_STRATEGY=allow
  - GUARD_ALLOWED_EXTS=mkv,mp4,m4v,avi,ts,m2ts,mov,webm
  - GUARD_EXT_DELETE_IF_ANY_BLOCKED=1

  - LOG_LEVEL=INFO

Movie Focus

Optimized for movie downloads with pre-air checking, ISO cleanup and strict file type filtering.

Enhanced movie configuration with TMDB integration

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
environment:
  - QBIT_HOST=http://qbittorrent:8080
  - QBIT_USER=admin
  - QBIT_PASS=your_password_here
  - QBIT_ALLOWED_CATEGORIES=radarr

  # Movie pre-air checking with TMDB as primary source
  - ENABLE_PREAIR_CHECK=1
  - RADARR_URL=http://radarr:7878
  - RADARR_APIKEY=your_radarr_api_key_here
  - RADARR_PREAIR_CATEGORIES=radarr
  - TMDB_APIKEY=your_tmdb_api_key_here  # Primary: digital/physical release dates

  # Optional: Additional cross-verification
  - INTERNET_CHECK_PROVIDER=both
  - TVDB_APIKEY=your_tvdb_api_key_here

  # Movie-optimized grace periods
  - EARLY_GRACE_HOURS=12  # Longer grace for movie releases
  - EARLY_HARD_LIMIT_HOURS=168  # 1 week maximum

  # Enable ISO cleanup for movie disc images
  - ENABLE_ISO_CHECK=1
  - MIN_KEEPABLE_VIDEO_MB=100

  # Enhanced logging for release date verification
  - LOG_LEVEL=DETAILED

TMDB Integration

TMDB provides authoritative digital and physical release dates, significantly improving movie pre-air accuracy compared to Radarr metadata alone.

Advanced file management with selective unchecking

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
environment:
  - QBIT_HOST=http://qbittorrent:8080
  - QBIT_USER=admin
  - QBIT_PASS=your_password_here
  - QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr

  # Enable selective file unchecking (default behavior)
  - GUARD_UNCHECK_BLOCKED_FILES=1

  # Use allowlist strategy for precise control
  - GUARD_EXT_STRATEGY=allow
  - GUARD_ALLOWED_EXTS=mkv,mp4,m4v,avi,ts,m2ts,mov,webm,srt,ass,sub,idx

  # Only delete torrent if ALL files are blocked
  - GUARD_EXT_DELETE_IF_ALL_BLOCKED=1
  - GUARD_EXT_DELETE_IF_ANY_BLOCKED=0

  # Enhanced logging to see what's being unchecked
  - LOG_LEVEL=DETAILED

  # Standard integrations
  - ENABLE_PREAIR_CHECK=1
  - SONARR_URL=http://sonarr:8989
  - SONARR_APIKEY=your_sonarr_api_key_here
  - RADARR_URL=http://radarr:7878
  - RADARR_APIKEY=your_radarr_api_key_here
  - ENABLE_ISO_CHECK=1

Selective Behavior

With these settings, torrents with mixed content will have unwanted files unchecked (priority 0) while keeping wanted files. Torrents are tagged with guard:partial for identification.

Safe configuration for testing and debugging

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
environment:
  # Dry run mode - no actual deletions
  - QBIT_DRY_RUN=1

  # Debug logging for troubleshooting
  - LOG_LEVEL=DEBUG

  # Fast polling for immediate testing
  - WATCH_POLL_SECONDS=1.0

  # Process existing torrents on startup
  - WATCH_PROCESS_EXISTING_AT_START=1

  # Short timeouts to fail fast during testing
  - SONARR_TIMEOUT_SEC=10
  - RADARR_TIMEOUT_SEC=10

  # Minimal metadata wait time
  - METADATA_MAX_WAIT_SEC=30

  # Standard connection settings
  - QBIT_HOST=http://qbittorrent:8080
  - QBIT_USER=admin
  - QBIT_PASS=your_password_here
  - QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr

  # Enable features for testing
  - ENABLE_PREAIR_CHECK=1
  - ENABLE_ISO_CHECK=1
  - SONARR_URL=http://sonarr:8989
  - SONARR_APIKEY=your_sonarr_api_key_here
  - RADARR_URL=http://radarr:7878
  - RADARR_APIKEY=your_radarr_api_key_here
  - TMDB_APIKEY=your_tmdb_api_key_here  # Optional: For testing movie release dates

Dry Run Mode

This configuration runs in dry-run mode and won't actually delete torrents. Perfect for testing.

☁ Kubernetes Examples

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
apiVersion: v1
kind: ConfigMap
metadata:
  name: qbit-guard-config
data:
  QBIT_HOST: "http://qbittorrent:8080"
  QBIT_USER: "admin"
  QBIT_ALLOWED_CATEGORIES: "tv-sonarr,radarr"
  ENABLE_PREAIR_CHECK: "1"
  SONARR_URL: "http://sonarr:8989"
  EARLY_GRACE_HOURS: "6"
  EARLY_HARD_LIMIT_HOURS: "72"
  INTERNET_CHECK_PROVIDER: "tvmaze"
  ENABLE_ISO_CHECK: "1"
  MIN_KEEPABLE_VIDEO_MB: "50"
  LOG_LEVEL: "INFO"
YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
apiVersion: v1
kind: Secret
metadata:
  name: qbit-guard-secrets
type: Opaque
stringData:
  QBIT_PASS: "your_qbittorrent_password"
  SONARR_APIKEY: "your_sonarr_api_key"
  RADARR_APIKEY: "your_radarr_api_key"
  TVDB_APIKEY: "your_tvdb_api_key"
  TMDB_APIKEY: "your_tmdb_api_key"
YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
apiVersion: apps/v1
kind: Deployment
metadata:
  name: qbit-guard
spec:
  replicas: 1
  selector:
    matchLabels:
      app: qbit-guard
  template:
    metadata:
      labels:
        app: qbit-guard
    spec:
      containers:
      - name: qbit-guard
        image: ghcr.io/gengines/qbit-guard:latest
        envFrom:
        - configMapRef:
            name: qbit-guard-config
        - secretRef:
            name: qbit-guard-secrets
        resources:
          limits:
            memory: "256Mi"
            cpu: "250m"
          requests:
            memory: "128Mi"
            cpu: "100m"

📚 Next Steps