Files

kelinfoxy cba45556c7 Complete documentation refactoring with 57 service docs

- Refactored README.md, getting-started.md, quick-reference.md
- Enhanced setup-homelab.sh with 9-step automated process
- Created services-overview.md with all stacks
- Added comprehensive documentation for 57 services in docs/service-docs/
- All services include: overview, configuration, resources, educational content
- Coverage: Core, Infrastructure, Dashboards, Media, Media-Extended, Home Assistant, Productivity, Utilities, Monitoring, Development stacks
- Educational focus with links to tutorials, videos, and guides

2026-01-12 18:03:12 -05:00

18 KiB

Raw Blame History

Sonarr - TV Show Automation

Overview
What is Sonarr?
Why Use Sonarr?
How It Works
Configuration in AI-Homelab
Official Resources
Educational Resources
Docker Configuration
Initial Setup
Advanced Topics
Troubleshooting

Overview

Category: Media Management & Automation
Docker Image: linuxserver/sonarr
Default Stack: media.yml
Web UI: https://sonarr.${DOMAIN} or http://SERVER_IP:8989
Authentication: Optional (configurable)
Ports: 8989

What is Sonarr?

Sonarr is a PVR (Personal Video Recorder) for Usenet and BitTorrent users. It watches for new episodes of your favorite shows and automatically downloads, sorts, and renames them. Think of it as your personal TV show manager that never sleeps.

Key Features

Automatic Downloads: Grabs new episodes as they air
Quality Management: Choose preferred qualities and upgrades
Calendar: See upcoming episodes at a glance
Series Tracking: Monitor all your shows in one place
Episode Management: Rename and organize automatically
Failed Download Handling: Retry with different releases
Notifications: Pushover, Telegram, Discord, etc.
Custom Scripts: Run actions on import
List Integration: Import shows from Trakt, IMDb, etc.
Multi-Language: Profiles for different audio/subtitle languages

Why Use Sonarr?

Never Miss Episodes: Automatic downloads when they air
Quality Upgrades: Replace with better quality over time
Organization: Consistent naming and folder structure
Time Saving: No manual searching and downloading
Metadata Management: Integrates with Plex/Jellyfin/Emby
Season Packs: Smart handling of season releases
Backlog Management: Track missing episodes
Multi-Show Management: Hundreds of shows easily
Smart Search: Finds best releases automatically
Integration Ecosystem: Works with downloaders and indexers

How It Works

New Episode Airs
       ↓
Sonarr Checks RSS Feeds (Prowlarr)
       ↓
Evaluates Releases (Quality, Size, etc.)
       ↓
Sends Best Release to Downloader
(qBittorrent via Gluetun VPN)
       ↓
Monitors Download Progress
       ↓
Download Completes
       ↓
Sonarr Imports File
       ↓
Renames & Moves to Library
(/mnt/media/tv/)
       ↓
Plex/Jellyfin Auto-Scans
       ↓
Episode Available for Watching

Configuration in AI-Homelab

Directory Structure

/opt/stacks/media/sonarr/config/    # Sonarr configuration
/mnt/downloads/                      # Download directory (from qBittorrent)
/mnt/media/tv/                       # Final TV library

TV Library Structure:
/mnt/media/tv/
  Show Name (Year)/
    Season 01/
      Show Name - S01E01 - Episode Name.mkv
      Show Name - S01E02 - Episode Name.mkv

Environment Variables

# User permissions (must match file ownership)
PUID=1000
PGID=1000

# Timezone (for air times)
TZ=America/New_York

Official Resources

Website: https://sonarr.tv
Wiki: https://wiki.servarr.com/sonarr
GitHub: https://github.com/Sonarr/Sonarr
Discord: https://discord.gg/sonarr
Reddit: https://reddit.com/r/sonarr
Docker Hub: https://hub.docker.com/r/linuxserver/sonarr

Educational Resources

Videos

Articles & Guides

Concepts to Learn

Quality Profiles: Define preferred qualities and upgrades
Custom Formats: Advanced release filtering (HDR, Dolby Vision, etc.)
Release Profiles: Preferred/ignored words
Indexers: Sources for releases (via Prowlarr)
Root Folders: Where shows are stored
Series Types: Standard, Daily, Anime
Season Packs: Full season releases
Cutoff: Quality to stop upgrading at

Docker Configuration

Complete Service Definition

sonarr:
  image: linuxserver/sonarr:latest
  container_name: sonarr
  restart: unless-stopped
  networks:
    - traefik-network
  ports:
    - "8989:8989"
  environment:
    - PUID=1000
    - PGID=1000
    - TZ=America/New_York
  volumes:
    - /opt/stacks/media/sonarr/config:/config
    - /mnt/media/tv:/tv
    - /mnt/downloads:/downloads
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.sonarr.rule=Host(`sonarr.${DOMAIN}`)"
    - "traefik.http.routers.sonarr.entrypoints=websecure"
    - "traefik.http.routers.sonarr.tls.certresolver=letsencrypt"
    - "traefik.http.routers.sonarr.middlewares=authelia@docker"
    - "traefik.http.services.sonarr.loadbalancer.server.port=8989"

Key Volume Mapping

volumes:
  - /opt/stacks/media/sonarr/config:/config     # Sonarr settings
  - /mnt/media/tv:/tv                            # TV library (final location)
  - /mnt/downloads:/downloads                    # Download client folder

Important: Sonarr needs access to both download location and final library location to perform hardlinking (instant moves without copying).

Initial Setup

First Access

Start Container:
```
docker compose up -d sonarr
```
Access Web UI:
- Local: http://SERVER_IP:8989
- Domain: https://sonarr.yourdomain.com
Initial Configuration:
- Settings → Media Management
- Settings → Profiles
- Settings → Indexers (via Prowlarr)
- Settings → Download Clients

Media Management Settings

Settings → Media Management:

Rename Episodes: ✓ Enable
Replace Illegal Characters: ✓ Enable
Standard Episode Format:
```
{Series Title} - S{season:00}E{episode:00} - {Episode Title} {Quality Full}
```
Example: Breaking Bad - S01E01 - Pilot Bluray-1080p.mkv

Daily Episode Format:

{Series Title} - {Air-Date} - {Episode Title} {Quality Full}

Anime Episode Format:

{Series Title} - S{season:00}E{episode:00} - {Episode Title} {Quality Full}

Series Folder Format:
```
{Series Title} ({Series Year})
```
Example: Breaking Bad (2008)
Season Folder Format:
```
Season {season:00}
```
Root Folders:
- Add: /tv
- This is where shows will be stored

File Management:

✓ Unmonitor Deleted Episodes
✓ Download Propers and Repacks: Prefer and Upgrade
✓ Analyze video files
✓ Use Hardlinks instead of Copy: Important for space saving!
Minimum Free Space: 100 MB

Quality Profiles

Settings → Profiles → Quality Profiles:

Default profile is fine, but recommended setup:

HD-1080p Profile:

Create new profile: "HD-1080p"
Upgrades Allowed: ✓
Upgrade Until: Bluray-1080p
Qualities (in order):
- Bluray-1080p
- WEB-1080p
- HDTV-1080p
- WEBDL-1080p
Save

4K Profile (optional):

Name: "Ultra HD"
Upgrade Until: Bluray-2160p
Qualities: 4K variants

Follow TRaSH Guides for optimal quality profiles: https://trash-guides.info/Sonarr/Sonarr-Setup-Quality-Profiles/

Download Client Setup

Settings → Download Clients → Add → qBittorrent:

Name: qBittorrent
Enable: ✓
Host: gluetun (container name, if qBittorrent behind VPN)
Port: 8080
Username: admin (default)
Password: adminadmin (default, change this!)
Category: tv-sonarr
Priority: Normal
Test → Save

Important Settings:

✓ Remove Completed: Download completed and seeding
✓ Remove Failed: Downloads that fail

Indexer Setup (via Prowlarr)

Sonarr should get indexers automatically from Prowlarr (Sync):

Manual Check:

Settings → Indexers
Should see synced indexers from Prowlarr
Each should show "Test: Successful"

If Not Synced:

Go to Prowlarr → Settings → Apps
Add Sonarr application
Prowlarr Server: http://prowlarr:9696
Sonarr Server: http://sonarr:8989
API Key: From Sonarr → Settings → General → API Key

Adding Your First Show

Click "Add Series"
Search: Type show name (e.g., "Breaking Bad")
Select correct show from results
Configure:
- Root Folder: /tv
- Quality Profile: HD-1080p
- Series Type: Standard (or Daily/Anime)
- Season: All or specific seasons
- ✓ Start search for missing episodes
Add Series

Sonarr will:

Add show to database
Search for all missing episodes
Send downloads to qBittorrent
Monitor for new episodes

Advanced Topics

Custom Formats (v4)

Custom Formats allow advanced filtering of releases:

Settings → Custom Formats:

Common custom formats:

HDR: Prefer HDR versions
Dolby Vision: DV support
Streaming Services: Prefer specific services
Audio: Atmos, TrueHD, DTS-X
Release Groups: Prefer trusted groups

Importing from TRaSH Guides: https://trash-guides.info/Sonarr/sonarr-setup-custom-formats/

Example Use Cases:

Prefer HDR for 4K TV
Avoid streaming service logos/watermarks
Prefer lossless audio
Prefer specific release groups (RARBG, etc.)

Release Profiles (Deprecated in v4)

Replaced by Custom Formats in Sonarr v4.

Series Types

Standard:

Regular TV shows
Season/Episode numbering
Example: Breaking Bad S01E01

Daily:

Talk shows, news
Air date naming
Example: The Daily Show 2024-01-01

Anime:

Absolute episode numbering
Example: One Piece 001

Set when adding series.

Auto-Tagging

Settings → Import Lists:

Automatically add shows from:

Trakt Lists: Your watchlist, popular shows
IMDb Lists: Custom lists
Simkl Lists: Another tracking service
MyAnimeList: For anime

Example: Trakt Watchlist

Settings → Import Lists → Add → Trakt Watchlist
Authenticate with Trakt
Configure:
- Quality Profile: HD-1080p
- Root Folder: /tv
- Monitor: All Episodes
- Search: Yes
Save

Shows added to your Trakt watchlist auto-import to Sonarr!

Notifications

Settings → Connect → Add Notification:

Popular options:

Plex: Update libraries on import
Jellyfin: Scan library
Discord: New episode notifications
Telegram: Mobile alerts
Pushover: Push notifications
Email: SMTP notifications

Example: Plex

Add → Plex Media Server
Host: plex
Port: 32400
Auth Token: Get from Plex
Triggers: On Import, On Upgrade
Test → Save

Custom Scripts

Settings → Connect → Custom Script:

Run scripts on events:

On Download
On Import
On Upgrade
On Rename
On Delete

Example Use Cases:

Notify external service
Trigger backup
Custom file processing
Update external database

Multiple Sonarr Instances

Run separate instances for different use cases:

sonarr-4k.yml:

sonarr-4k:
  image: linuxserver/sonarr:latest
  container_name: sonarr-4k
  ports:
    - "8990:8989"
  volumes:
    - /opt/stacks/media/sonarr-4k/config:/config
    - /mnt/media/tv-4k:/tv
    - /mnt/downloads:/downloads
  environment:
    - PUID=1000
    - PGID=1000
    - TZ=America/New_York

Use Cases:

Separate 4K library
Different quality standards
Anime-specific instance
Testing new settings

Season Pack Handling

Settings → Indexers → Edit Indexer:

Prefer Season Pack: Yes
Season Pack Only: No

How It Works:

Sonarr prefers full season downloads
More efficient than individual episodes
Only grabs if meets quality requirements

V4 vs V3

Sonarr v4 (Current):

Custom Formats replace Release Profiles
Better quality management
Improved UI
SQLite database

Sonarr v3 (Legacy):

Release Profiles
Older interface
Still supported

Migration:

Automatic on update
Backup first!
Read changelog

Troubleshooting

Sonarr Can't Find Releases

# Check indexers
# Settings → Indexers → Test All

# Check Prowlarr sync
docker logs prowlarr | grep sonarr

# Check search
# Series → Manual Search → View logs

# Common causes:
# - No indexers configured
# - Indexers down
# - Release doesn't exist yet
# - Quality profile too restrictive

Downloads Not Importing

# Check download client connection
# Settings → Download Clients → Test

# Check permissions
ls -la /mnt/downloads/
ls -la /mnt/media/tv/

# Ensure Sonarr can access both
docker exec sonarr ls /downloads
docker exec sonarr ls /tv

# Check logs
docker logs sonarr | grep -i import

# Common issues:
# - Permission denied
# - Wrong category in qBittorrent
# - File still seeding
# - Hardlink failed (different filesystems)

Wrong Series Match

# Edit series
# Series → Select Show → Edit

# Fix match
# Search for correct series
# Update Series

# Or delete and re-add with correct match

Upgrade Loop

# Sonarr keeps downloading same episode

# Check quality profile
# Ensure "Upgrade Until" is set correctly

# Check custom formats
# May be scoring releases incorrectly

# Check file already exists
# Series → Select Episode → Delete file
# Sonarr may think existing file doesn't meet requirements

Hardlink Errors

# Error: "Unable to hardlink"

# Check if /downloads and /tv on same filesystem
df -h /mnt/downloads
df -h /mnt/media/tv

# Must be on same mount point for hardlinks
# If different, Sonarr will copy instead

# Fix: Ensure both on same disk/volume

Database Corruption

# Stop Sonarr
docker stop sonarr

# Backup database
cp /opt/stacks/media/sonarr/config/sonarr.db /opt/backups/

# Check database
sqlite3 /opt/stacks/media/sonarr/config/sonarr.db "PRAGMA integrity_check;"

# If corrupted, restore from backup
# Or let Sonarr rebuild (loses settings)
# rm /opt/stacks/media/sonarr/config/sonarr.db

docker start sonarr

Performance Optimization

RSS Sync Interval

Settings → Indexers → Options:

RSS Sync Interval: 15 minutes (default)
Lower for faster new episode detection
Higher to reduce indexer load

Reduce Database Size

# Stop Sonarr
docker stop sonarr

# Vacuum database
sqlite3 /opt/stacks/media/sonarr/config/sonarr.db "VACUUM;"

# Remove old history
# Settings → General → History Cleanup: 30 days

docker start sonarr

Optimize Scanning