Install

You need API keys from Sonarr and/or Radarr (Settings, General, Security). A SABnzbd URL and API key are optional and turn on the stall watcher. Start with DRY_RUN=true for a day if you want to watch first.

Unraid

Search Community Apps for plungarr and install. Fill in the Sonarr and Radarr URLs and API keys, and SABnzbd if you use it. Click “Show more settings” for the action policies, notifications, a second instance, and the timezone.

Prefer the template file directly, for example on a system without Community Apps? Download it into your user templates and it shows up under “Add Container”:

curl -fsSL https://raw.githubusercontent.com/stove-bison/plungarr/master/templates/plungarr.xml \
  -o /boot/config/plugins/dockerMan/templates-user/plungarr.xml

Reload the Docker page, click “Add Container”, and pick plungarr from the template list.

State lives in /mnt/user/appdata/plungarr. The container makes that folder writable for the user it runs as (PUID/PGID, default 99/100), so no manual permissions step is needed.

Optional: to have plungarr report (or delete) leftover job folders in SABnzbd's completed directory, map that directory to /downloads under “Show more settings” and set LEFTOVER_DIRS to the category folders inside it, for example /downloads/tv,/downloads/movies. Read-only is enough for reporting.

Updating on Unraid

Docker tab, “Check for Updates”, then “apply update” on plungarr. Updates pull the new image only. New settings added in later versions do not appear on an existing container's form; add them with “Add another Path, Port, Variable” in Edit, or reinstall from the template.

Docker Compose

git clone https://github.com/stove-bison/plungarr.git && cd plungarr
cp .env.example .env    # fill in your URLs and API keys
docker compose up -d --build

Or use the published image directly:

services:
  plungarr:
    image: ghcr.io/stove-bison/plungarr:latest
    container_name: plungarr
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./state:/state
      # optional, for the leftover-folder sweep (LEFTOVER_DIRS=/downloads/tv,...):
      # - /path/to/sabnzbd/complete:/downloads:ro

Watch it work:

docker logs -f plungarr

Which URL to use

The URL must be reachable from inside the container. On bridge networking that means the host's LAN address, for example http://192.168.1.20:8989, not localhost, which inside the container is plungarr itself. If an app runs behind a URL base, include it: http://host:8989/sonarr.

Two Sonarrs, or two Radarrs

Add numbered instances. SONARR_URL is instance one; SONARR_2_URL and SONARR_2_API_KEY add a second, up to _9. Same for RADARR_. Optional SONARR_2_NAME labels it in logs and digests, for example anime. On Unraid the second-instance fields are under “Show more settings”.

If both instances share one SABnzbd, configure both in the same plungarr container. The stall watcher only removes a download as an orphan when no configured instance owns it. Two separate containers would each see the other's downloads as ownerless.

Timezone

Daily, weekly and monthly digests fire at NOTIFY_DIGEST_HOUR in the container's local time. Set TZ, for example Europe/London or America/New_York, or the container runs on UTC.

What the state file holds

/state/janitor-state.json keeps first-seen times for the age gate, blocklist counts for the loop guard, which notifications have been sent, and which library files have already been reported. Losing it costs nothing except a few minutes of re-gating. Dry runs never read or write it.

Running the tests

node --check janitor.mjs && node --test

Tests use mocked APIs and a local HTTP fixture. They never contact a real Sonarr, Radarr or SABnzbd.