claude-home/tdarr/examples/tdarr-node-configurations.md

# Tdarr Node Container Configurations

## Overview
Complete examples for running Tdarr transcoding nodes in containers, covering both CPU-only and GPU-accelerated setups.

## CPU-Only Configuration (Docker Compose)

For systems without GPU or when GPU isn't needed:

```yaml
version: "3.4"
services:
  tdarr-node:
    container_name: tdarr-node-cpu
    image: ghcr.io/haveagitgat/tdarr_node:latest
    restart: unless-stopped
    environment:
      - TZ=America/Chicago
      - UMASK_SET=002
      - nodeName=local-workstation-cpu
      - serverIP=YOUR_TDARR_SERVER_IP  # Replace with your tdarr server IP
      - serverPort=8266
      - inContainer=true
      - ffmpegVersion=6
    volumes:
      # Mount your media from the same NAS share as the server
      - /path/to/your/media:/media  # Replace with your local media mount
      # Temp directory for transcoding cache
      - ./temp:/temp
```

**Use case**: 
- CPU-only transcoding
- Testing Tdarr functionality
- Systems without dedicated GPU
- When GPU drivers aren't available

## GPU-Accelerated Configuration (Podman)

**Recommended for Fedora/RHEL/CentOS/Nobara systems:**

### Mapped Node (Direct Media Access)
```bash
podman run -d --name tdarr-node-gpu-mapped \
    --gpus all \
    --restart unless-stopped \
    -e TZ=America/Chicago \
    -e UMASK_SET=002 \
    -e nodeName=local-workstation-gpu-mapped \
    -e serverIP=10.10.0.43 \
    -e serverPort=8266 \
    -e inContainer=true \
    -e ffmpegVersion=6 \
    -e NVIDIA_DRIVER_CAPABILITIES=all \
    -e NVIDIA_VISIBLE_DEVICES=all \
    -v /mnt/NV2/tdarr-cache:/cache \
    -v /mnt/media/TV:/media/TV \
    -v /mnt/media/Movies:/media/Movies \
    -v /mnt/media/tdarr/tdarr-cache-clean:/temp \
    ghcr.io/haveagitgat/tdarr_node:latest
```

### Unmapped Node (Downloads Files)
```bash
podman run -d --name tdarr-node-gpu-unmapped \
    --gpus all \
    --restart unless-stopped \
    -e TZ=America/Chicago \
    -e UMASK_SET=002 \
    -e nodeName=local-workstation-gpu-unmapped \
    -e serverIP=10.10.0.43 \
    -e serverPort=8266 \
    -e inContainer=true \
    -e ffmpegVersion=6 \
    -e NVIDIA_DRIVER_CAPABILITIES=all \
    -e NVIDIA_VISIBLE_DEVICES=all \
    -v /mnt/NV2/tdarr-cache:/cache \
    -v /mnt/media:/media \
    -v /mnt/media/tdarr/tdarr-cache-clean:/temp \
    ghcr.io/haveagitgat/tdarr_node:latest
```

**Use cases**:
- **Mapped**: Direct media access, faster processing, no file downloads
- **Unmapped**: Works when network shares aren't available locally
- Hardware video encoding/decoding (NVENC/NVDEC)
- High-performance transcoding with NVMe cache
- Multiple concurrent streams
- Fedora-based systems where Podman works better than Docker

## GPU-Accelerated Configuration (Docker)

**For Ubuntu/Debian systems where Docker GPU support works:**

```yaml
version: "3.4"
services:
  tdarr-node:
    container_name: tdarr-node-gpu
    image: ghcr.io/haveagitgat/tdarr_node:latest
    restart: unless-stopped
    environment:
      - TZ=America/Chicago
      - UMASK_SET=002
      - nodeName=local-workstation-gpu
      - serverIP=YOUR_TDARR_SERVER_IP
      - serverPort=8266
      - inContainer=true
      - ffmpegVersion=6
      - NVIDIA_DRIVER_CAPABILITIES=all
      - NVIDIA_VISIBLE_DEVICES=all
    volumes:
      - /path/to/your/media:/media
      - ./temp:/temp
    deploy:
      resources:
        reservations:
          devices:
          - driver: nvidia
            count: all
            capabilities: [gpu]
```

## Configuration Parameters

### Required Environment Variables
- `TZ`: Timezone (e.g., `America/Chicago`)
- `nodeName`: Unique identifier for this node
- `serverIP`: IP address of Tdarr server
- `serverPort`: Tdarr server port (typically 8266)
- `inContainer`: Set to `true` for containerized deployments
- `ffmpegVersion`: FFmpeg version to use (6 recommended)

### GPU-Specific Variables
- `NVIDIA_DRIVER_CAPABILITIES`: Set to `all` for full GPU access
- `NVIDIA_VISIBLE_DEVICES`: `all` for all GPUs, or specific GPU IDs

### Volume Mounts
- `/media`: Mount point for media files (must match server configuration)
- `/temp`: Temporary directory for transcoding cache

## Platform-Specific Recommendations

### Fedora/RHEL/CentOS/Nobara
- **GPU**: Use Podman (Docker Desktop has GPU issues)
- **CPU**: Docker or Podman both work fine

### Ubuntu/Debian  
- **GPU**: Use Docker with nvidia-container-toolkit
- **CPU**: Docker recommended

### Testing GPU Functionality

Verify GPU access inside container:
```bash
# For Podman
podman exec tdarr-node-gpu nvidia-smi

# For Docker  
docker exec tdarr-node-gpu nvidia-smi
```

Test NVENC encoding:
```bash
# For Podman
podman exec tdarr-node-gpu /usr/local/bin/tdarr-ffmpeg -f lavfi -i testsrc2=duration=5:size=1920x1080:rate=30 -c:v h264_nvenc -t 5 /tmp/test.mp4

# For Docker
docker exec tdarr-node-gpu /usr/local/bin/tdarr-ffmpeg -f lavfi -i testsrc2=duration=5:size=1920x1080:rate=30 -c:v h264_nvenc -t 5 /tmp/test.mp4
```

## Troubleshooting

- **GPU not detected**: See `reference/docker/nvidia-gpu-troubleshooting.md`
- **Permission issues**: Ensure proper UMASK_SET and volume permissions
- **Connection issues**: Verify serverIP and firewall settings
- **Performance issues**: Monitor CPU/GPU utilization during transcoding

## Related Documentation

- `patterns/docker/gpu-acceleration.md` - GPU acceleration patterns
- `reference/docker/nvidia-gpu-troubleshooting.md` - Detailed GPU troubleshooting
- `start-tdarr-gpu-podman.sh` - Ready-to-use Podman startup script