Arpad Krejczinger
66e3249ced
- Enhanced configuration and security guidance - Updated setup procedures and best practices
121 lines
3.4 KiB
Markdown
121 lines
3.4 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```yaml
|
|
volumes:
|
|
- /mnt/nas/torrent:/downloads
|
|
- qbittorrent-config:/config
|
|
```
|
|
|
|
### Logs
|
|
|
|
Check container logs for issues:
|
|
```bash
|
|
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 |