Skip to content

setup-integrations.md

Latest commit

 

History

History
279 lines (184 loc) · 5.59 KB

setup-integrations.md

File metadata and controls

279 lines (184 loc) · 5.59 KB

🔧 PlexPulse Integration Setup Guide

This document describes how to correctly configure Plex, Radarr, and Sonarr to work with PlexPulse.

It focuses on operator setup and delete semantics, not architecture. For system design and guarantees, see the main README.md.

🧠 Before You Begin (Important Context)

PlexPulse is reactive, not controlling.

  • PlexPulse does not delete files
  • PlexPulse does not decide what Radarr/Sonarr delete
  • PlexPulse does not modify Plex libraries
  • PlexPulse reacts to outcomes, not intentions

Radarr and Sonarr decide:

  • what to delete
  • whether files are removed
  • how items are unmanaged

PlexPulse observes:

  • Plex library state
  • Arr deletion intent
  • Then reconciles Watchlist state safely

Keep this distinction in mind while configuring.

🎞 Plex Setup

Required Tokens

PlexPulse requires:

  • A Plex Server Token (for library observation)
  • A Plex Account Token (for Watchlist removal via Discover)

Ensure these are correctly set in your .env.

Plex Permissions & Behaviour

No special Plex settings are required beyond:

  • Normal library access
  • Account Watchlist enabled

PlexPulse:

  • Queries Plex libraries via API
  • Removes Watchlist items via Plex Discover API
  • Never deletes media
  • Never alters library configuration

If Plex still reports an item, PlexPulse treats it as present, regardless of Arr activity.

🎬 Radarr Setup (Movies)

Radarr is a core integration.

It provides:

  • Movie deletion intent
  • Immediate Watchlist cleanup signals

Radarr Webhook Configuration

In Radarr:

  1. Go to Settings → Connect
  2. Click Add → Webhook
  3. Configure as follows:
Setting Value
URL http://<plexpulse-host>:8080/webhook/radarr
Method POST
On Delete ✅ Enabled
On Movie File Delete ❌ Disabled
On Movie File Delete (Upgrade) ❌ Disabled

Save the webhook.

Radarr Delete Semantics (CRITICAL)

Radarr allows multiple deletion modes.
PlexPulse does not enforce these — you do.

Common Radarr delete actions:

Radarr Action Effect PlexPulse Reaction
Delete Movie + Files Movie removed from disk and Plex Watchlist removed immediately (if resolvable)
Delete Movie (keep files) Movie removed from Radarr only Plex still reports item → no Watchlist removal
Unmonitor No deletion No effect
Manual file deletion Plex decides PlexPulse reacts after baseline

👉 Recommendation
If your intent is full removal, ensure Radarr deletes:

  • the movie
  • the files
  • the Plex-visible media

PlexPulse reacts only after Plex no longer reports the item.

What Radarr Sends

Radarr provides:

  • movie.tmdbId

PlexPulse maps this to:

tmdb://<tmdbId>

This identifier is used for:

  • Watchlist resolution
  • Ledger intent annotation

📺 Sonarr Setup (Series)

Sonarr is also a core integration.

It provides:

  • Series deletion intent
  • Immediate Watchlist cleanup signals

Sonarr Webhook Configuration

In Sonarr:

  1. Go to Settings → Connect
  2. Click Add → Webhook
  3. Configure as follows:
Setting Value
URL http://<plexpulse-host>:8080/webhook/sonarr
Method POST
On Delete ✅ Enabled
On Episode File Delete ❌ Disabled
On Episode File Delete (Upgrade) ❌ Disabled

Save the webhook.

Sonarr Delete Semantics (CRITICAL)

Sonarr deletion behaviour is more nuanced than Radarr.

Sonarr Action Effect PlexPulse Reaction
Delete Series + Files Series removed from Plex Watchlist removed immediately
Delete Series (keep files) Files remain Plex still reports series → no removal
Delete Season only Partial presence No Watchlist removal
Delete Episode Series still present No Watchlist removal

👉 Recommendation
Only expect Watchlist removal when:

  • the entire series is removed
  • Plex no longer reports the series

Partial deletions do not qualify.

What Sonarr Sends

Sonarr provides:

  • series.tvdbId

PlexPulse maps this to:

tvdb://<tvdbId>

This is the canonical identifier for shows.

🔔 Webhook Behaviour & Expectations

Best-Effort, Not Guaranteed

Webhooks are:

  • Fast
  • Opportunistic
  • Non-authoritative

If a webhook arrives:

  • before the Watchlist index is built
  • during Plex refresh lag
  • during container startup

…it may not immediately match.

This is expected and safe.

Recovery Is Automatic

Missed webhooks are not a failure.

PlexPulse will correct state during:

  • the next Baseline
  • the next Reconcile run
  • container restart

Correctness always converges.

🔍 Verifying Integration Health

Check Watchlist Index Readiness

curl http://<plexpulse-host>:8080/admin/index-ready

Expected:

{ "ready": true }

Rebuild Watchlist Index Manually

curl -X POST http://<plexpulse-host>:8080/admin/rebuild-index

🛡 Safety Summary

PlexPulse guarantees:

  • No file deletions
  • No forced Arr actions
  • No Plex library mutation
  • No reliance on webhooks alone

Radarr and Sonarr remain fully in control of deletion behaviour.

PlexPulse observes, records, and reconciles — nothing more.

📌 Final Notes

If something looks wrong:

  • Check Plex first
  • Then check Arr deletion behaviour
  • Then run Baseline + Reconcile

Do not attempt to “fix” issues by forcing webhooks.

The system is designed to converge safely.