homelab/docs/qbittorrent-setup.md

qBittorrent Setup Guide

This document provides comprehensive step-by-step instructions for setting up qBittorrent in your homelab environment, including both automated deployment and manual configuration.

Prerequisites

• qBittorrent container running via Docker
• NAS directory structure set up at /mnt/nas/torrent/
• Nginx reverse proxy configured for /qbt/ path

Current NAS Structure

The following directory structure should already exist:

/mnt/nas/torrent/
├── watch/
│   ├── music/
│   ├── videos/
│   ├── documents/
│   └── private/
└── complete/
    ├── music/
    ├── videos/
    ├── documents/
    └── private/

Manual Configuration Steps

1. Access qBittorrent Web UI

1. Open your browser and navigate to: https://ak-homelab.duckdns.org/qbt/
2. Login with:
   • Username: admin
   • Password: Check Docker logs for temporary password:

     docker logs qbittorrent 2>&1 | grep "temporary password"
     

3. IMPORTANT: Change the default password on first login

2. Configure Basic Settings

1. Go to Tools → Options → Downloads
2. Set Default Torrent Management Mode: Automatic
3. Set Default Save Path: /downloads/complete
4. Enable Auto managed torrents
5. Click Apply

3. Create Download Categories

Right-click in the main torrent area and select Add category for each:

Category	Save Path
music	/downloads/complete/music
videos	/downloads/complete/videos
documents	/downloads/complete/documents
private	/downloads/complete/private

4. Set Up Watch Folders

1. Go to Tools → Options → Downloads
2. Navigate to Monitored Folder section
3. Click Add to create watch folders:

Watch Folder Path	Category
/downloads/watch/music	music
/downloads/watch/videos	videos
/downloads/watch/documents	documents
/downloads/watch/private	private

5. Test Configuration

1. Download a test .torrent file
2. Drop it into /mnt/nas/torrent/watch/music/
3. Verify it appears in qBittorrent with the correct category
4. Confirm it downloads to /mnt/nas/torrent/complete/music/

6. Optional: Hardlink Organization

After confirming downloads work correctly, you can set up automatic hardlinking to organize files for Jellyfin access:

./scripts/organize-torrents.py

This creates hardlinks from completed torrents to appropriate media directories without duplicating files.

Troubleshooting

Common Issues

1. Permission errors: Ensure qBittorrent container has read/write access to mounted volumes
2. Watch folders not working: Check that the paths are correctly mapped in docker-compose.yml
3. Categories not auto-assigning: Verify watch folder paths match exactly

Docker Volume Mapping

Ensure your docker-compose.yml includes these volume mappings:

volumes:
  - /mnt/nas/torrent:/downloads
  - qbittorrent-config:/config

Logs

Check container logs for issues:

docker logs qbittorrent

Security Recommendations

1. Change default admin password immediately
2. Enable 2FA if available in your qBittorrent version
3. Consider using authentication bypass only for local network access
4. Regularly update the container image for security patches