# qBittorrent Manual Setup Guide

This guide provides step-by-step instructions for manually configuring qBittorrent through the web UI to work with the existing NAS directory structure.

## 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