Docker Installation¶

Docker is the recommended way to run Torrentarr. It provides an isolated, consistent environment that works across all platforms.

Prerequisites¶

Docker installed (Get Docker)
Docker Compose installed (optional but recommended)
qBittorrent running and accessible
At least one Arr instance (Radarr, Sonarr, or Lidarr)

Quick Start¶

Using Docker Run¶

docker run -d \
  --name torrentarr \
  --restart unless-stopped \
  -p 6969:6969 \
  -v /path/to/config:/config \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=America/New_York \
  feramance/torrentarr:latest

Using Docker Compose¶

Create a docker-compose.yml file:

version: "3.8"

services:
  torrentarr:
    image: feramance/torrentarr:latest
    container_name: torrentarr
    restart: unless-stopped
    ports:
      - "6969:6969"
    volumes:
      - /path/to/config:/config
      - /path/to/downloads:/downloads  # Same as qBittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York

Then run:

docker-compose up -d

Configuration¶

Environment Variables¶

Variable	Default	Description
`TORRENTARR_CONFIG`	`/config/config.toml`	Path to config file
`PUID`	`1000`	User ID for file permissions
`PGID`	`1000`	Group ID for file permissions
`TZ`	`UTC`	Timezone (e.g., `America/New_York`, `Europe/London`)

Volume Mapping¶

Path Mapping is Critical

Torrentarr, qBittorrent, and your Arr instances MUST all see the same paths for downloads. This is the #1 cause of issues with Docker setups.

Required volumes:

/config - Configuration files and database
/downloads - Must match qBittorrent and Arr download paths

Example:

If qBittorrent downloads to /downloads/torrents, and Radarr expects files in /downloads/torrents, then Torrentarr needs the same mount:

services:
  qbittorrent:
    volumes:
      - /mnt/storage/downloads:/downloads

  radarr:
    volumes:
      - /mnt/storage/downloads:/downloads

  torrentarr:
    volumes:
      - /mnt/storage/downloads:/downloads  # Same path!

Docker Compose Example (Complete)¶

Here's a complete example with qBittorrent, Radarr, and Torrentarr:

version: "3.8"

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - WEBUI_PORT=8080
    volumes:
      - /path/to/qbittorrent/config:/config
      - /path/to/downloads:/downloads
    ports:
      - "8080:8080"
      - "6881:6881"
      - "6881:6881/udp"
    restart: unless-stopped

  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - /path/to/radarr/config:/config
      - /path/to/downloads:/downloads
      - /path/to/movies:/movies
    ports:
      - "7878:7878"
    restart: unless-stopped

  torrentarr:
    image: feramance/torrentarr:latest
    container_name: torrentarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - /path/to/torrentarr/config:/config
      - /path/to/downloads:/downloads  # Must match!
    ports:
      - "6969:6969"
    restart: unless-stopped
    depends_on:
      - qbittorrent
      - radarr

Image Tags¶

Tag	Description
`latest`	Latest stable release (recommended)
`nightly`	Latest development build (bleeding edge)
`5.x.x`	Specific version (e.g., `5.5.5`)

Recommended: Use latest for production, nightly for testing new features.

First Run¶

Start the container:
```
docker-compose up -d
```
Check logs:
```
docker logs -f torrentarr
```
Configuration file created: Torrentarr will generate /config/config.toml on first run
Stop the container to edit config:
```
docker-compose down
```
Edit the configuration:
```
nano /path/to/config/config.toml
```
Start again:
```
docker-compose up -d
```

See the First Run Guide for detailed configuration steps.

Accessing the WebUI¶

Once running, access the WebUI at:

http://localhost:6969/ui

Or replace localhost with your server's IP address.

Updating¶

Docker Compose¶

docker-compose pull
docker-compose up -d

Docker Run¶

docker pull feramance/torrentarr:latest
docker stop torrentarr
docker rm torrentarr
# Run the docker run command again

Auto-Updates

Torrentarr has a built-in auto-update feature that works in Docker. It will pull the latest image and restart the container automatically if configured.

Troubleshooting Quick Reference¶

Having issues? Here are the most common fixes. For detailed troubleshooting, see the Docker Troubleshooting Guide.

Quick Fixes¶

Issue	Quick Fix
Container won't start	`docker logs torrentarr` to check errors
Permission denied	`sudo chown -R 1000:1000 /path/to/config`
Can't connect to qBittorrent	Use container name (`qbittorrent:8080`) if on same network
Path not found	Ensure identical volume mappings across all containers
Database locked	Stop duplicate containers: `docker ps --filter name=torrentarr`
High CPU/memory	Set `LogLevel = "INFO"` and add resource limits

Essential Diagnostics¶

# Check logs
docker logs torrentarr

# Check container status
docker ps | grep torrentarr

# Check networking
docker exec torrentarr ping -c 3 qbittorrent

# Check paths
docker exec torrentarr ls -la /downloads

Common Configuration Fixes¶

Network connectivity:

[qBit]
Host = "http://qbittorrent:8080"  # Use container name

[[Radarr]]
URI = "http://radarr:7878"  # Use container name

Permissions (docker-compose.yml):

environment:
  - PUID=1000  # Match your user's UID
  - PGID=1000  # Match your user's GID

All containers must use identical volume mappings:

volumes:
  - /mnt/storage/downloads:/downloads  # Same path everywhere

For comprehensive troubleshooting including import failures, database issues, and performance optimization, see the Docker Troubleshooting Guide.

Advanced Configuration¶

Custom Network¶

Create a dedicated network for your media stack:

networks:
  media:
    driver: bridge

services:
  torrentarr:
    networks:
      - media
    # ... rest of config

Resource Limits¶

Limit CPU and memory usage:

services:
  torrentarr:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Health Checks¶

Add a health check:

services:
  torrentarr:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6969/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Docker Compose Examples¶

Example 1: Complete Media Stack¶

Full stack with qBittorrent, Radarr, Sonarr, and Torrentarr:

version: "3.8"

networks:
  media:
    driver: bridge

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent:/config
      - /mnt/storage/downloads:/downloads
    ports:
      - "8080:8080"
      - "6881:6881"
      - "6881:6881/udp"
    networks:
      - media
    restart: unless-stopped

  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./radarr:/config
      - /mnt/storage/downloads:/downloads
      - /mnt/storage/movies:/movies
    ports:
      - "7878:7878"
    networks:
      - media
    restart: unless-stopped

  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./sonarr:/config
      - /mnt/storage/downloads:/downloads
      - /mnt/storage/tv:/tv
    ports:
      - "8989:8989"
    networks:
      - media
    restart: unless-stopped

  torrentarr:
    image: feramance/torrentarr:latest
    container_name: torrentarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./torrentarr:/config
      - /mnt/storage/downloads:/downloads
    ports:
      - "6969:6969"
    networks:
      - media
    depends_on:
      - qbittorrent
      - radarr
      - sonarr
    restart: unless-stopped

Example 2: With Overseerr¶

Add request management:

version: "3.8"

networks:
  media:
    driver: bridge

services:
  # ... qbittorrent, radarr, sonarr from above ...

  overseerr:
    image: lscr.io/linuxserver/overseerr:latest
    container_name: overseerr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./overseerr:/config
    ports:
      - "5055:5055"
    networks:
      - media
    restart: unless-stopped

  torrentarr:
    image: feramance/torrentarr:latest
    container_name: torrentarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./torrentarr:/config
      - /mnt/storage/downloads:/downloads
    ports:
      - "6969:6969"
    networks:
      - media
    depends_on:
      - qbittorrent
      - radarr
      - sonarr
      - overseerr
    restart: unless-stopped

Example 3: With VPN¶

Run qBittorrent through VPN:

version: "3.8"

services:
  vpn:
    image: qmcgaw/gluetun
    container_name: vpn
    cap_add:
      - NET_ADMIN
    environment:
      - VPN_SERVICE_PROVIDER=nordvpn
      - VPN_TYPE=openvpn
      - OPENVPN_USER=your_username
      - OPENVPN_PASSWORD=your_password
      - SERVER_COUNTRIES=United States
    volumes:
      - ./gluetun:/gluetun
    ports:
      - "8080:8080"  # qBittorrent WebUI
      - "6881:6881"  # qBittorrent
      - "6881:6881/udp"
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "service:vpn"  # Route through VPN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent:/config
      - /mnt/storage/downloads:/downloads
    depends_on:
      - vpn
    restart: unless-stopped

  # radarr, sonarr, torrentarr don't need VPN
  radarr:
    image: lscr.io/linuxserver/radarr:latest
    # ... normal config, NOT through VPN

Example 4: With Traefik Reverse Proxy¶

version: "3.8"

networks:
  web:
    external: true
  media:
    driver: bridge

services:
  torrentarr:
    image: feramance/torrentarr:latest
    container_name: torrentarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./torrentarr:/config
      - /mnt/storage/downloads:/downloads
    networks:
      - web
      - media
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.torrentarr.rule=Host(`torrentarr.yourdomain.com`)"
      - "traefik.http.routers.torrentarr.entrypoints=websecure"
      - "traefik.http.routers.torrentarr.tls.certresolver=letsencrypt"
      - "traefik.http.services.torrentarr.loadbalancer.server.port=6969"
    restart: unless-stopped

Best Practices¶

1. Use Named Volumes for Config¶

volumes:
  torrentarr-config:

services:
  torrentarr:
    volumes:
      - torrentarr-config:/config  # Persistent, managed by Docker
      - /mnt/storage/downloads:/downloads

2. Set Proper Restart Policies¶

services:
  torrentarr:
    restart: unless-stopped  # Don't restart if manually stopped

3. Use Health Checks¶

services:
  torrentarr:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6969/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

4. Enable Logging Limits¶

services:
  torrentarr:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

5. Use Docker Secrets for API Keys¶

secrets:
  radarr_api_key:
    file: ./secrets/radarr_api_key.txt

services:
  torrentarr:
    secrets:
      - radarr_api_key
    environment:
      - RADARR_API_KEY_FILE=/run/secrets/radarr_api_key

Migration from Other Setups¶

From Native Install¶

Copy config:

cp ~/.config/Torrentarr/config.toml /path/to/docker/config/

Copy database:

cp ~/.config/Torrentarr/*.db /path/to/docker/config/

Update paths in config.toml:
Change /home/user/downloads to /downloads
Start Docker container

From Unraid¶

Add Torrentarr from Community Applications
Map paths to match existing setup
Import existing config if desired

Performance Tips¶

1. Optimize Volume Performance¶

Use delegated/cached mounts on macOS:

volumes:
  - /mnt/storage/downloads:/downloads:delegated

2. Reduce Image Size¶

Use specific version tags:

image: feramance/torrentarr:5.5.5  # Not latest

3. Limit Log Output¶

environment:
  - ConsoleLevel in config.toml [Settings]  # Not DEBUG

4. Use Local DNS¶

services:
  torrentarr:
    dns:
      - 1.1.1.1
      - 1.0.0.1
    extra_hosts:
      - "radarr:192.168.1.100"
      - "qbittorrent:192.168.1.100"

Next Steps¶

Ready to configure Torrentarr?

Configure qBittorrent - qBittorrent Setup Guide
Configure Arr Instances - Arr Configuration Guide
First Run - Complete the First Run Setup
Troubleshooting - Docker-Specific Issues

Configuration File Reference - Complete TOML syntax
Environment Variables - All ENV vars
Path Mapping Guide - Fix path issues
Docker Troubleshooting - Comprehensive Docker guide
WebUI Access - Access the web interface