kelin/EZ-Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f92424ed6d006c0670fda849105eeeee07f71aa1
EZ-Homelab/docs/service-docs/readarr.md
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

14 KiB
Raw Blame History

Readarr - Book & Audiobook Automation

Table of Contents

Overview

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

What is Readarr?

Readarr is an ebook and audiobook collection manager for Usenet and BitTorrent users. It's part of the *arr family (like Sonarr for TV and Radarr for movies), but specifically designed for books. Readarr monitors for new book releases, automatically downloads them, and organizes your library with proper metadata.

Key Features

  • Automatic Downloads: New releases from monitored authors
  • Quality Management: Ebook vs audiobook, formats
  • Author Management: Track favorite authors
  • Series Tracking: Monitor book series
  • Calendar: Upcoming releases
  • Metadata Enrichment: Book covers, descriptions, ISBNs
  • Format Support: EPUB, MOBI, AZW3, PDF, MP3, M4B
  • GoodReads Integration: Import reading lists
  • Multiple Libraries: Fiction, non-fiction, audiobooks
  • Calibre Integration: Works with Calibre libraries

Why Use Readarr?

  1. Never Miss Releases: Auto-download new books from favorite authors
  2. Library Organization: Consistent structure and naming
  3. Format Flexibility: Multiple ebook formats
  4. Series Management: Track reading order
  5. Metadata Automation: Covers, descriptions, authors
  6. GoodReads Integration: Import want-to-read lists
  7. Audiobook Support: Unified management
  8. Time Saving: No manual searching
  9. Free & Open Source: No cost
  10. Calibre Compatible: Works with existing libraries

How It Works

New Book Release (Author Monitored)
          ↓
Readarr Checks RSS Feeds (Prowlarr)
          ↓
Evaluates Releases (Format, Quality)
          ↓
Sends to qBittorrent (via Gluetun VPN)
          ↓
Download Completes
          ↓
Readarr Imports & Organizes
          ↓
Library Updated
(/mnt/media/books/)
          ↓
Calibre-Web / Calibre Access

Configuration in AI-Homelab

Directory Structure

/opt/stacks/media-extended/readarr/config/    # Readarr configuration
/mnt/downloads/complete/books-readarr/        # Downloaded books
/mnt/media/books/                             # Final book library

Library Structure:
/mnt/media/books/
  Author Name/
    Series Name/
      Book 01 - Title (Year).epub
      Book 02 - Title (Year).epub

Environment Variables

# User permissions
PUID=1000
PGID=1000

# Timezone
TZ=America/New_York

Official Resources

Educational Resources

Videos

Articles & Guides

Concepts to Learn

  • Metadata Profiles: Preferred ebook formats
  • Quality Profiles: Quality and format preferences
  • Release Profiles: Preferred/avoided release groups
  • Root Folders: Library locations
  • Author vs Book: Monitoring modes
  • GoodReads Lists: Import reading lists
  • Calibre Content Server: Integration

Docker Configuration

Complete Service Definition

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

Note: Use develop tag for latest features. Readarr is still in active development.

Initial Setup

First Access

  1. Start Container:

    docker compose up -d readarr

  2. Access Web UI:

    • Local: http://SERVER_IP:8787
    • Domain: https://readarr.yourdomain.com

  3. Initial Configuration:

    • Settings → Media Management
    • Settings → Profiles
    • Settings → Indexers (via Prowlarr)
    • Settings → Download Clients

Media Management Settings

Settings → Media Management:

  1. Rename Books: ✓ Enable

  2. Replace Illegal Characters: ✓ Enable

  3. Standard Book Format:

    {Author Name}/{Series Title}/{Series Title} - {Book #} - {Book Title} ({Release Year})

    Example: Brandon Sanderson/Mistborn/Mistborn - 01 - The Final Empire (2006).epub

  4. Author Folder Format:

    {Author Name}

  5. Root Folders:

    • Add: /books

File Management:

  • ✓ Unmonitor Deleted Books
  • ✓ Use Hardlinks instead of Copy
  • Minimum Free Space: 100 MB
  • ✓ Import Extra Files

Metadata Profiles

Settings → Profiles → Metadata Profiles:

Default profile includes:

  • Ebook formats (EPUB, MOBI, AZW3, PDF)
  • Audiobook formats (MP3, M4B, M4A)

Custom Profile Example:

  • Name: "Ebooks Only"
  • Include: EPUB, MOBI, AZW3, PDF
  • Exclude: Audio formats

Quality Profiles

Settings → Profiles → Quality Profiles:

Ebook Profile:

  1. Name: "Ebook - High Quality"
  2. Upgrades Allowed: ✓
  3. Upgrade Until: EPUB
  4. Qualities (in order):
    • EPUB
    • AZW3
    • MOBI
    • PDF (lowest priority)

Audiobook Profile:

  1. Name: "Audiobook"
  2. Upgrade Until: M4B (best for chapters)
  3. Qualities:
    • M4B
    • MP3

Download Client Setup

Settings → Download Clients → Add → qBittorrent:

  1. Name: qBittorrent
  2. Host: gluetun
  3. Port: 8080
  4. Username: admin
  5. Password: Your password
  6. Category: books-readarr
  7. Test → Save

Indexer Setup (via Prowlarr)

Prowlarr Integration:

  • Prowlarr → Settings → Apps → Add Readarr
  • Sync Categories: Books/Ebook, Books/Audiobook
  • Auto-syncs indexers to Readarr

Verify:

  • Settings → Indexers
  • Should see synced indexers from Prowlarr

Adding Your First Author

  1. Click "Add New"
  2. Search: Author name (e.g., "Brandon Sanderson")
  3. Select correct author
  4. Configure:
    • Root Folder: /books
    • Monitor: All Books (or Future Books)
    • Metadata Profile: Standard
    • Quality Profile: Ebook - High Quality
    • ✓ Search for missing books
  5. Add Author

Adding Individual Books

  1. Library → Add New → Search for a book
  2. Search: Book title or ISBN
  3. Select correct book
  4. Configure:
    • Root Folder: /books
    • Monitor: Yes
    • Quality Profile: Ebook - High Quality
    • ✓ Start search for book
  5. Add Book

Advanced Topics

GoodReads Integration

Import Reading Lists:

Settings → Import Lists → Add → GoodReads Lists:

  1. Access Token: Get from GoodReads
  2. User ID: Your GoodReads ID
  3. List Name: "to-read" or custom list
  4. Root Folder: /books
  5. Quality Profile: Ebook - High Quality
  6. Monitor: Yes
  7. Search on Add: Yes
  8. Save

Auto-sync periodically to import new books from your GoodReads lists.

Calibre Integration

If you use Calibre:

Settings → Calibre:

  1. Host: IP of Calibre server
  2. Port: 8080 (default)
  3. Username/Password: If Calibre requires auth
  4. Library: Name of Calibre library
  5. Save

Options:

  • Use Calibre for metadata
  • Export to Calibre on import
  • Sync with Calibre library

Multiple Libraries

Separate ebook and audiobook libraries:

readarr-audio:
  image: linuxserver/readarr:develop
  container_name: readarr-audio
  ports:
    - "8788:8787"
  volumes:
    - /opt/stacks/media-extended/readarr-audio/config:/config
    - /mnt/media/audiobooks:/books
    - /mnt/downloads:/downloads
  environment:
    - PUID=1000
    - PGID=1000

Separate instance for audiobooks with different quality profile.

Metadata Management

Edit Metadata:

  • Select book → Edit → Metadata
  • Change title, author, description
  • Upload custom cover
  • Lock fields to prevent overwriting

Refresh Metadata:

  • Right-click book → Refresh & Scan
  • Re-fetches from online sources

Series Management

Monitor Entire Series:

  1. Add author
  2. View author page
  3. Series tab → Select series
  4. Monitor entire series
  5. Readarr tracks all books in series

Reading Order:

  • Readarr shows series order
  • Books numbered sequentially
  • Missing books highlighted

Custom Scripts

Settings → Connect → Custom Script:

Run scripts on events:

  • On Download
  • On Import
  • On Upgrade
  • On Rename
  • On Delete

Use Cases:

  • Convert formats (MOBI → EPUB)
  • Sync to e-reader
  • Backup to cloud
  • Update external database

Notifications

Settings → Connect:

Popular notifications:

  • Calibre: Update library on import
  • Discord: New book alerts
  • Telegram: Mobile notifications
  • Email: SMTP alerts
  • Custom Webhook: External integrations

Troubleshooting

Readarr Not Finding Books

# Check indexers
# Settings → Indexers → Test All

# Check Prowlarr sync
docker logs prowlarr | grep readarr

# Manual search
# Book → Manual Search → View logs

# Common issues:
# - No indexers with book categories
# - Book not released yet
# - Quality profile too restrictive
# - Wrong book metadata (try ISBN search)

Downloads Not Importing

# Check permissions
ls -la /mnt/downloads/complete/books-readarr/
ls -la /mnt/media/books/

# Fix ownership
sudo chown -R 1000:1000 /mnt/media/books/

# Verify Readarr access
docker exec readarr ls /downloads
docker exec readarr ls /books

# Check logs
docker logs readarr | grep -i import

# Common issues:
# - Permission denied
# - Wrong category in qBittorrent
# - File format not in metadata profile
# - Hardlink failed (different filesystems)

Wrong Author/Book Match

# Search by ISBN for accurate match
# Add New → Search: ISBN-13 number

# Edit book/author
# Library → Select → Edit
# Search for correct match

# Check metadata sources
# Settings → Metadata → Verify sources enabled

Database Corruption

# Stop Readarr
docker stop readarr

# Backup database
cp /opt/stacks/media-extended/readarr/config/readarr.db /opt/backups/

# Check integrity
sqlite3 /opt/stacks/media-extended/readarr/config/readarr.db "PRAGMA integrity_check;"

# Restore from backup if corrupted
docker start readarr

Performance Optimization

RSS Sync Interval

Settings → Indexers → Options:

  • RSS Sync Interval: 60 minutes
  • Books release less frequently than TV/movies

Database Optimization

# Stop Readarr
docker stop readarr

# Vacuum database
sqlite3 /opt/stacks/media-extended/readarr/config/readarr.db "VACUUM;"

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

docker start readarr

Security Best Practices

  1. Enable Authentication:

    • Settings → General → Security
    • Authentication: Required

  2. API Key Security:

    • Keep API key secure
    • Regenerate if compromised

  3. Reverse Proxy:

    • Use Traefik + Authelia
    • Don't expose port 8787 publicly

  4. Regular Backups:

    • Backup /config directory
    • Includes database and settings

Backup Strategy

Critical Files:

/opt/stacks/media-extended/readarr/config/readarr.db     # Database
/opt/stacks/media-extended/readarr/config/config.xml     # Settings
/opt/stacks/media-extended/readarr/config/Backup/        # Auto backups

Backup Script:

#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR=/opt/backups/readarr

cp /opt/stacks/media-extended/readarr/config/readarr.db $BACKUP_DIR/readarr-$DATE.db
find $BACKUP_DIR -name "readarr-*.db" -mtime +7 -delete

Integration with Other Services

Readarr + Prowlarr

  • Centralized indexer management
  • Auto-sync book indexers

Readarr + qBittorrent (via Gluetun)

  • Download books via VPN
  • Category-based organization

Readarr + Calibre-Web

  • Web interface for reading
  • Library management
  • Format conversion

Readarr + Calibre

  • Professional ebook management
  • Format conversion
  • Metadata editing
  • E-reader sync

Summary

Readarr is the ebook/audiobook automation tool offering:

  • Automatic book downloads
  • Author and series tracking
  • Format management (EPUB, MOBI, MP3, M4B)
  • GoodReads integration
  • Calibre compatibility
  • Free and open-source

Perfect for:

  • Avid readers
  • Audiobook enthusiasts
  • Series completionists
  • GoodReads users
  • Calibre users
  • Book collectors

Key Points:

  • Use develop tag for latest features
  • Monitor favorite authors
  • GoodReads list integration
  • Multiple format support
  • Calibre compatibility
  • Series tracking
  • ISBN search for accuracy

Remember:

  • Still in active development
  • Use ISBN for accurate matching
  • Separate ebook/audiobook profiles
  • Integrate with Calibre-Web for reading
  • Monitor series, not just books
  • Regular backups recommended

Readarr completes the *arr stack for comprehensive media automation!

Reference in New Issue View Git Blame Copy Permalink