brianpooe/homelab-blueprint
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab-blueprint/docs/arr-stack/recyclarr.md
Brian Pooe 1815beadf4 refactor: restructure docs, sync stacks with Caddyfile, harden compose templates 
- Add compose stacks for apps already proxied by Caddy: bento-pdf,
  it-tools, paperless-ngx, and beszel-hub (with Makefile targets)
- Remove the unused Vault stack and the drawio Caddyfile block
- Fix Caddyfile gramps upstream to port 80 to match the compose file
- Bring immich and gramps-web up to the shared template pattern
  (no-new-privileges, log rotation, memory limits, healthchecks)
- Single-quote vaultwarden SSO_AUDIENCE_TRUSTED so regex values like
  ^\d{18}$ render as valid YAML
- Move root docs into kebab-case topic folders, rebuild the docs index
  to cover every doc, and fix all broken links
2026-07-03 17:45:16 +02:00

4.8 KiB
Raw Permalink Blame History

Recyclarr Configuration Guide (v8)

Recyclarr syncs TRaSH Guides quality profiles and custom formats to Sonarr and Radarr. This repository now uses Recyclarr v8 with guide-backed quality profiles (no include templates).

Quick Start

1. Generate recyclarr.yml

./substitute_env.sh docker-compose-files/arr-stack/config/recyclarr_template.yml /opt/arr-stack/appdata/recyclarr/recyclarr.yml .env
nano /opt/arr-stack/appdata/recyclarr/recyclarr.yml

2. Add API Keys

  • Sonarr: Settings -> General -> Security -> API Key
  • Radarr: Settings -> General -> Security -> API Key

3. Keep Docker Service URLs

Use service names, not localhost:

sonarr:
  sonarr-main:
    base_url: http://sonarr:8989

radarr:
  radarr-main:
    base_url: http://radarr:7878

Template Behavior (v8)

The included template configures:

  • Sonarr quality definition: series
  • Sonarr guide-backed profiles:
    • WEB-1080p (72dae194fc92bf828f32cde7744e51a1)
    • WEB-2160p (d1498e7d189fbe6c7110ceaabb7473e6)
  • Radarr quality definition: movie
  • Radarr guide-backed profiles:
    • UHD Bluray + WEB (64fb5f9858489bdac2af690e27c8f42f)
    • HD Bluray + WEB (d1d67249d3890e49bc12e275d989a7e9)
  • Language CF override for non-English audio with -10000 score:
    • Sonarr: 69aa1e159f97d860440b04cd6d590c4f
    • Radarr: 0dc8aec3bd1c47cd6c40c46ecd27e846
  • Sonarr DSCP is explicitly managed at score 75:
    • Sonarr: dc5f2bb0e0262155b5fedd0f6c5d2b55

Example v8 Configuration

This is the same shape used by docker-compose-files/arr-stack/config/recyclarr_template.yml:

sonarr:
  sonarr-main:
    base_url: http://sonarr:8989
    api_key: your_sonarr_api_key
    delete_old_custom_formats: true
    quality_definition:
      type: series
    quality_profiles:
      - trash_id: 72dae194fc92bf828f32cde7744e51a1
        name: WEB-1080p
        reset_unmatched_scores:
          enabled: true
      - trash_id: d1498e7d189fbe6c7110ceaabb7473e6
        name: WEB-2160p
        reset_unmatched_scores:
          enabled: true
    custom_formats:
      - trash_ids:
          - 69aa1e159f97d860440b04cd6d590c4f
        assign_scores_to:
          - name: WEB-1080p
            score: -10000
          - name: WEB-2160p
            score: -10000
      - trash_ids:
          - dc5f2bb0e0262155b5fedd0f6c5d2b55
        assign_scores_to:
          - name: WEB-1080p
            score: 75
          - name: WEB-2160p
            score: 75

radarr:
  radarr-main:
    base_url: http://radarr:7878
    api_key: your_radarr_api_key
    delete_old_custom_formats: true
    quality_definition:
      type: movie
    quality_profiles:
      - trash_id: 64fb5f9858489bdac2af690e27c8f42f
        name: UHD Bluray + WEB
        reset_unmatched_scores:
          enabled: true
      - trash_id: d1d67249d3890e49bc12e275d989a7e9
        name: HD Bluray + WEB
        reset_unmatched_scores:
          enabled: true
    custom_formats:
      - trash_ids:
          - 0dc8aec3bd1c47cd6c40c46ecd27e846
        assign_scores_to:
          - name: UHD Bluray + WEB
            score: -10000
          - name: HD Bluray + WEB
            score: -10000

Validate and Sync

# Confirm instance names from config
docker exec recyclarr recyclarr config list

# Dry run first
docker exec recyclarr recyclarr sync --preview

# Apply
docker exec recyclarr recyclarr sync

Common Issues

base_url must start with 'http' or 'https'

Cause: malformed URL or empty value.

Fix:

# Wrong
base_url: localhost:8989
base_url:

# Correct
base_url: http://sonarr:8989

Unable to find include template with name ...

Cause: old pre-v8 config using include: - template:.

Fix:

# Regenerate v8 config from current template
./substitute_env.sh docker-compose-files/arr-stack/config/recyclarr_template.yml /opt/arr-stack/appdata/recyclarr/recyclarr.yml .env

# Recreate recyclarr with v8 image from compose template
./substitute_env.sh docker-compose-files/arr-stack/template.yaml docker-compose.arr-stack.yml .env
docker-compose -f docker-compose.arr-stack.yml pull recyclarr
docker-compose -f docker-compose.arr-stack.yml up -d recyclarr

replace_existing_custom_formats validation error

Cause: this key was removed in v8.

Fix: remove replace_existing_custom_formats from your config.

Upgrade Notes

  • This repository pins Recyclarr to ghcr.io/recyclarr/recyclarr:8.6.0.
  • Always run sync --preview before sync after changing quality/profile settings.

References