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
parent 906e6008ea
commit cba45556c7
69 changed files with 24404 additions and 1522 deletions
--- a/docs/service-docs/readarr.md
+++ b/docs/service-docs/readarr.md
@@ -0,0 +1,595 @@
+# Readarr - Book & Audiobook Automation
+
+## Table of Contents
+- [Overview](#overview)
+- [What is Readarr?](#what-is-readarr)
+- [Why Use Readarr?](#why-use-readarr)
+- [How It Works](#how-it-works)
+- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
+- [Official Resources](#official-resources)
+- [Educational Resources](#educational-resources)
+- [Docker Configuration](#docker-configuration)
+- [Initial Setup](#initial-setup)
+- [Advanced Topics](#advanced-topics)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+**Category:** Media Management & Automation  
+**Docker Image:** [linuxserver/readarr](https://hub.docker.com/r/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
+
+```bash
+# User permissions
+PUID=1000
+PGID=1000
+
+# Timezone
+TZ=America/New_York
+```
+
+## Official Resources
+
+- **Website:** https://readarr.com
+- **Wiki:** https://wiki.servarr.com/readarr
+- **GitHub:** https://github.com/Readarr/Readarr
+- **Discord:** https://discord.gg/readarr
+- **Reddit:** https://reddit.com/r/readarr
+- **Docker Hub:** https://hub.docker.com/r/linuxserver/readarr
+
+## Educational Resources
+
+### Videos
+- [Readarr Setup Guide](https://www.youtube.com/results?search_query=readarr+setup)
+- [*arr Stack Complete Guide](https://www.youtube.com/results?search_query=readarr+sonarr+radarr)
+- [Readarr + Calibre](https://www.youtube.com/results?search_query=readarr+calibre)
+
+### Articles & Guides
+- [Official Documentation](https://wiki.servarr.com/readarr)
+- [Servarr Wiki](https://wiki.servarr.com/)
+- [Calibre Integration](https://wiki.servarr.com/readarr/settings#calibre)
+
+### 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
+
+```yaml
+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:**
+   ```bash
+   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:**
+
+```yaml
+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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:**
+```bash
+/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:**
+```bash
+#!/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!