CLAUDE: Add media server documentation with Jellyfin setup
- Add CONTEXT.md with GPU transcoding patterns - Add Jellyfin ubuntu-manticore setup guide (10.10.0.226) - Document GPU resource sharing with Tdarr 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
782067344a
commit
5bd5e31798
133
media-servers/CONTEXT.md
Normal file
133
media-servers/CONTEXT.md
Normal file
@ -0,0 +1,133 @@
|
|||||||
|
# Media Servers - Technology Context
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
Media server infrastructure for home lab environments, covering streaming services like Jellyfin and Plex with hardware-accelerated transcoding, library management, and client discovery.
|
||||||
|
|
||||||
|
## Current Deployments
|
||||||
|
|
||||||
|
### Jellyfin on ubuntu-manticore
|
||||||
|
- **Location**: 10.10.0.226:8096
|
||||||
|
- **GPU**: NVIDIA GTX 1070 (NVENC/NVDEC)
|
||||||
|
- **Documentation**: `jellyfin-ubuntu-manticore.md`
|
||||||
|
|
||||||
|
### Plex (Existing)
|
||||||
|
- **Location**: TBD (potential migration to ubuntu-manticore)
|
||||||
|
- **Note**: Currently running elsewhere, may migrate for GPU access
|
||||||
|
|
||||||
|
## Architecture Patterns
|
||||||
|
|
||||||
|
### GPU-Accelerated Transcoding
|
||||||
|
**Pattern**: Hardware encoding/decoding for real-time streaming
|
||||||
|
```yaml
|
||||||
|
# Docker Compose GPU passthrough
|
||||||
|
deploy:
|
||||||
|
resources:
|
||||||
|
reservations:
|
||||||
|
devices:
|
||||||
|
- driver: nvidia
|
||||||
|
count: all
|
||||||
|
capabilities: [gpu]
|
||||||
|
environment:
|
||||||
|
- NVIDIA_DRIVER_CAPABILITIES=all
|
||||||
|
- NVIDIA_VISIBLE_DEVICES=all
|
||||||
|
```
|
||||||
|
|
||||||
|
### Storage Strategy
|
||||||
|
**Pattern**: Tiered storage for different access patterns
|
||||||
|
- **Config**: Local SSD (small, fast database access)
|
||||||
|
- **Cache**: Local NVMe (transcoding temp, thumbnails)
|
||||||
|
- **Media**: Network storage (large capacity, read-only mount)
|
||||||
|
|
||||||
|
### Multi-Service GPU Sharing
|
||||||
|
**Pattern**: Resource allocation when multiple services share GPU
|
||||||
|
- Limit background tasks (Tdarr) to fewer concurrent jobs
|
||||||
|
- Prioritize real-time services (Jellyfin/Plex playback)
|
||||||
|
- Consumer GPUs limited to 2-3 concurrent NVENC sessions
|
||||||
|
|
||||||
|
## Common Configurations
|
||||||
|
|
||||||
|
### NVIDIA GPU Setup
|
||||||
|
```bash
|
||||||
|
# Verify GPU in container
|
||||||
|
docker exec <container> nvidia-smi
|
||||||
|
|
||||||
|
# Check encoder/decoder utilization
|
||||||
|
nvidia-smi dmon -s u
|
||||||
|
```
|
||||||
|
|
||||||
|
### Media Volume Mounts
|
||||||
|
```yaml
|
||||||
|
volumes:
|
||||||
|
- /mnt/truenas/media:/media:ro # Read-only for safety
|
||||||
|
```
|
||||||
|
|
||||||
|
### Client Discovery
|
||||||
|
- **Jellyfin**: UDP 7359
|
||||||
|
- **Plex**: UDP 32410-32414, GDM
|
||||||
|
|
||||||
|
## Integration Points
|
||||||
|
|
||||||
|
### Watch History Sync
|
||||||
|
- **Tool**: watchstate (ghcr.io/arabcoders/watchstate)
|
||||||
|
- **Method**: API-based sync between services
|
||||||
|
- **Note**: NFO files do NOT store watch history
|
||||||
|
|
||||||
|
### Tdarr Integration
|
||||||
|
- Tdarr pre-processes media for optimal streaming
|
||||||
|
- Shared GPU resources require coordination
|
||||||
|
- See `tdarr/CONTEXT.md` for transcoding system details
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Performance
|
||||||
|
1. Use NVMe for cache/transcoding temp directories
|
||||||
|
2. Mount media read-only to prevent accidental modifications
|
||||||
|
3. Enable hardware transcoding for all supported codecs
|
||||||
|
4. Limit concurrent transcodes based on GPU capability
|
||||||
|
|
||||||
|
### Reliability
|
||||||
|
1. Use `restart: unless-stopped` for containers
|
||||||
|
2. Separate config from cache (different failure modes)
|
||||||
|
3. Monitor disk space on cache volumes
|
||||||
|
4. Regular database backups (config directory)
|
||||||
|
|
||||||
|
### Security
|
||||||
|
1. Run containers as non-root (PUID/PGID)
|
||||||
|
2. Use read-only media mounts
|
||||||
|
3. Limit network exposure (internal LAN only)
|
||||||
|
4. Regular container image updates
|
||||||
|
|
||||||
|
## GPU Compatibility Notes
|
||||||
|
|
||||||
|
### NVIDIA Pascal (GTX 10-series)
|
||||||
|
- NVENC: H.264, HEVC (no B-frames for HEVC)
|
||||||
|
- NVDEC: H.264, HEVC, VP8, VP9
|
||||||
|
- Sessions: 2 concurrent (consumer card limit)
|
||||||
|
|
||||||
|
### NVIDIA Turing+ (RTX 20-series and newer)
|
||||||
|
- NVENC: H.264, HEVC (with B-frames), AV1
|
||||||
|
- NVDEC: H.264, HEVC, VP8, VP9, AV1
|
||||||
|
- Sessions: 3+ concurrent
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
1. **No GPU in container**: Check Docker/Podman GPU passthrough config
|
||||||
|
2. **Transcoding failures**: Verify codec support for your GPU generation
|
||||||
|
3. **Slow playback start**: Check network mount performance
|
||||||
|
4. **Cache filling up**: Monitor trickplay/thumbnail generation
|
||||||
|
|
||||||
|
### Diagnostic Commands
|
||||||
|
```bash
|
||||||
|
# GPU status
|
||||||
|
nvidia-smi
|
||||||
|
|
||||||
|
# Container GPU access
|
||||||
|
docker exec <container> nvidia-smi
|
||||||
|
|
||||||
|
# Encoder/decoder utilization
|
||||||
|
nvidia-smi dmon -s u
|
||||||
|
|
||||||
|
# Container logs
|
||||||
|
docker logs <container> 2>&1 | tail -50
|
||||||
|
```
|
||||||
154
media-servers/jellyfin-ubuntu-manticore.md
Normal file
154
media-servers/jellyfin-ubuntu-manticore.md
Normal file
@ -0,0 +1,154 @@
|
|||||||
|
# Jellyfin Setup on ubuntu-manticore
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
Jellyfin media server deployed on ubuntu-manticore (10.10.0.226) with NVIDIA GTX 1070 for hardware-accelerated transcoding.
|
||||||
|
|
||||||
|
**Date**: 2025-12-04
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
ubuntu-manticore (10.10.0.226)
|
||||||
|
└── jellyfin (container)
|
||||||
|
├── Web UI: http://10.10.0.226:8096
|
||||||
|
├── Discovery: UDP 7359
|
||||||
|
├── Config: ~/docker/jellyfin/config/
|
||||||
|
├── Cache: /mnt/NV2/jellyfin-cache (NVMe)
|
||||||
|
├── Media: /mnt/truenas/media (read-only)
|
||||||
|
└── GPU: GTX 1070 (NVENC/NVDEC)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Docker Compose Configuration
|
||||||
|
|
||||||
|
**Location**: `~/docker/jellyfin/docker-compose.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
jellyfin:
|
||||||
|
image: jellyfin/jellyfin:latest
|
||||||
|
container_name: jellyfin
|
||||||
|
restart: unless-stopped
|
||||||
|
environment:
|
||||||
|
- PUID=1000
|
||||||
|
- PGID=1000
|
||||||
|
- TZ=America/Chicago
|
||||||
|
- NVIDIA_DRIVER_CAPABILITIES=all
|
||||||
|
- NVIDIA_VISIBLE_DEVICES=all
|
||||||
|
ports:
|
||||||
|
- "8096:8096" # Web UI
|
||||||
|
- "7359:7359/udp" # Client discovery
|
||||||
|
volumes:
|
||||||
|
- ./config:/config
|
||||||
|
- /mnt/NV2/jellyfin-cache:/cache
|
||||||
|
- /mnt/truenas/media:/media:ro
|
||||||
|
deploy:
|
||||||
|
resources:
|
||||||
|
reservations:
|
||||||
|
devices:
|
||||||
|
- driver: nvidia
|
||||||
|
count: all
|
||||||
|
capabilities: [gpu]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Storage Strategy
|
||||||
|
|
||||||
|
| Path | Location | Purpose |
|
||||||
|
|------|----------|---------|
|
||||||
|
| /config | ~/docker/jellyfin/config/ | Database, settings (small, OS drive) |
|
||||||
|
| /cache | /mnt/NV2/jellyfin-cache | Transcoding temp, trickplay images (large, NVMe) |
|
||||||
|
| /media | /mnt/truenas/media | Media library (read-only, network) |
|
||||||
|
|
||||||
|
**Why NVMe for cache:**
|
||||||
|
- Trickplay (timeline thumbnails) can grow to several GB
|
||||||
|
- Chapter images add up across large libraries
|
||||||
|
- Transcoding temp files need fast I/O
|
||||||
|
- Prevents filling up the boot drive
|
||||||
|
|
||||||
|
## GPU Hardware Acceleration
|
||||||
|
|
||||||
|
### Available Encoders
|
||||||
|
| Encoder | Status |
|
||||||
|
|---------|--------|
|
||||||
|
| h264_nvenc | Working |
|
||||||
|
| hevc_nvenc | Working |
|
||||||
|
| av1_nvenc | Working |
|
||||||
|
|
||||||
|
### Available Decoders
|
||||||
|
| Decoder | Status |
|
||||||
|
|---------|--------|
|
||||||
|
| h264_cuvid | Working |
|
||||||
|
| hevc_cuvid | Working |
|
||||||
|
| av1_cuvid | Working |
|
||||||
|
| vp8_cuvid | Working |
|
||||||
|
| vp9_cuvid | Working |
|
||||||
|
|
||||||
|
### Hardware Acceleration Types
|
||||||
|
- CUDA
|
||||||
|
- VAAPI
|
||||||
|
- QSV (not applicable - Intel)
|
||||||
|
- Vulkan
|
||||||
|
- OpenCL
|
||||||
|
|
||||||
|
### Configuring Hardware Transcoding
|
||||||
|
1. Go to **Dashboard** → **Playback** → **Transcoding**
|
||||||
|
2. Select **NVIDIA NVENC** as the hardware acceleration
|
||||||
|
3. Enable desired codecs for hardware decoding/encoding
|
||||||
|
4. Save changes
|
||||||
|
|
||||||
|
## Ports
|
||||||
|
|
||||||
|
| Port | Protocol | Purpose |
|
||||||
|
|------|----------|---------|
|
||||||
|
| 8096 | TCP | Web UI and API |
|
||||||
|
| 7359 | UDP | Client auto-discovery on LAN |
|
||||||
|
|
||||||
|
## Initial Setup
|
||||||
|
|
||||||
|
1. Access http://10.10.0.226:8096
|
||||||
|
2. Complete the setup wizard:
|
||||||
|
- Create admin account
|
||||||
|
- Add media libraries (Movies: /media/Movies, TV: /media/TV)
|
||||||
|
- Configure metadata providers
|
||||||
|
- Skip NFO savers (not needed unless sharing with Kodi)
|
||||||
|
3. Configure hardware transcoding in Dashboard
|
||||||
|
|
||||||
|
## Resource Sharing with Tdarr
|
||||||
|
|
||||||
|
Both Jellyfin and Tdarr share the GTX 1070. To prevent conflicts:
|
||||||
|
|
||||||
|
- **Tdarr**: Limited to 1 GPU worker
|
||||||
|
- **Jellyfin**: Handles real-time transcoding on-demand
|
||||||
|
- **GTX 1070**: Supports 2 concurrent NVENC sessions (consumer card limit)
|
||||||
|
|
||||||
|
Jellyfin transcodes are more latency-sensitive (users waiting for playback), so Tdarr yields priority by limiting concurrent jobs.
|
||||||
|
|
||||||
|
## Watch History Sync (Future)
|
||||||
|
|
||||||
|
For syncing watch history between Plex and Jellyfin:
|
||||||
|
- Use `ghcr.io/arabcoders/watchstate`
|
||||||
|
- Syncs via API, not NFO files
|
||||||
|
- NFO files don't store watch state
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### GPU Not Detected in Transcoding
|
||||||
|
```bash
|
||||||
|
# Verify GPU access in container
|
||||||
|
docker exec jellyfin nvidia-smi
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check Available Encoders
|
||||||
|
Container logs show available encoders on startup:
|
||||||
|
```bash
|
||||||
|
docker logs jellyfin 2>&1 | grep -i "available encoders"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Transcoding Failures
|
||||||
|
Check Jellyfin logs in Dashboard → Logs or:
|
||||||
|
```bash
|
||||||
|
docker logs jellyfin 2>&1 | tail -50
|
||||||
|
```
|
||||||
|
|
||||||
|
## Related Documentation
|
||||||
|
- Server inventory: `networking/server-inventory.md`
|
||||||
|
- Tdarr setup: `tdarr/ubuntu-manticore-setup.md`
|
||||||
Loading…
Reference in New Issue
Block a user