Cleanuparr Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Cleanuparr Setup Guide

Introduction

Cleanuparr watches your download client and the *arr queues and clears out downloads that are never going to finish. It removes torrents that are stalled, very slow, stuck fetching metadata, in an error state, or that Sonarr, Radarr or Lidarr refused to import. When it removes one, the *arr blocklists that release and searches for another, so the item still arrives, just from a better source.

It also has a malware blocker that skips unwanted files (such as .exe, .lnk or .scr posing as a video) inside torrents.

Supported clients include Transmission, qBittorrent, Deluge, Β΅Torrent, rTorrent and SABnzbd. This guide uses Transmission behind Gluetun (see Gluetun and Transmission Setup Guide).


Step 1: Environment Setup

  1. Add the port to your root .env file:
CLEANUPARR_PORT=11011
  1. Copy the Compose file to your active server folder and add it to the include: list of your server compose file:
cp compose/templates/cleanuparr.yaml compose/server1/cleanuparr.yaml
include:
  - ${COMPOSE_DIR}/cleanuparr.yaml
  1. Create the config folder and start the container:
mkdir -p ${DOCKERDIR}/cleanuparr/config
docker compose -p mediaserver -f docker-compose-server1.yaml up -d --no-deps cleanuparr

Step 2: Service Definition (cleanuparr.yaml)

services:
  cleanuparr:
    container_name: cleanuparr.${HOST_NAME}
    hostname: cleanuparr.${HOST_NAME}.lan
    image: ghcr.io/cleanuparr/cleanuparr:latest
    environment:
      PORT: 11011
      PUID: ${PUID}
      PGID: ${PGID}
      UMASK: "002"
      TZ: ${TZ}
    networks:
      - mediaserver
    ports:
      - "${CLEANUPARR_PORT}:11011"
    volumes:
      - ${DOCKERDIR}/cleanuparr/config:/config
      - ${USERDOWNLOAD}/Torrents:/downloads
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=Media"
      - "homepage.name=Cleanuparr"
      - "homepage.icon=cleanuparr.png"
      - "homepage.href=https://cleanuparr.${DOMAINNAME}/"
      - "homepage.description=Removes stalled and bad torrents, triggers a new search"

All settings live in the web UI and are stored in /config, not in environment variables. /downloads is mounted at the same path Transmission uses, so the optional Download Cleaner can see the files.


Step 3: First Run and Login

  1. Open http://<server-ip>:11011. The first screen asks you to create an admin account; nothing else works until you do (two-factor is optional).
  2. If the app is already behind Cloudflare Access (see Cloudflare Access: Zero Trust), you can skip the extra login on your own network: Settings β†’ General β†’ Authentication β†’ Disable auth for local addresses. Requests through the tunnel arrive from the cloudflared container's private address, so Access becomes the only login.
  3. Turn on Dry Run (Settings β†’ General) for the first few runs. Cleanuparr then only logs what it would do. Read the logs, then switch Dry Run off.

Step 4: Connect the Download Client and the *arrs

Download client: Settings β†’ Download Clients β†’ Add

  • Type: Transmission
  • Host: http://transmission.${HOST_NAME}:9091 (the Gluetun alias on the mediaserver network)
  • URL base: transmission
  • Username and password: the Transmission web UI login from .env
  • Use Test before saving.

Sonarr, Radarr, Lidarr: Settings β†’ Arrs β†’ add an instance for each

  • URL: http://sonarr.${HOST_NAME}:8989, http://radarr.${HOST_NAME}:7878, http://lidarr.${HOST_NAME}:8686
  • API key: each app's Settings β†’ General β†’ API Key
  • Version: the app's major version (for example Sonarr 4, Radarr 6, Lidarr 3)

Step 5: Recommended Settings

The Queue Cleaner adds a strike each run a download has a problem, and removes it when it reaches the limit. Strikes reset when the download makes progress, and after 24 hours with no new strike. With a run every 10 minutes, strikes convert to time like this:

Setting Value Roughly
Queue Cleaner schedule every 10 minutes (0 0/10 * * * ?)
Stall rule (no progress) 18 strikes, reset on progress 3 hours
Slow rule (under 20 KB/s) 36 strikes, reset on progress 6 hours
Downloading metadata 6 strikes 1 hour
Failed import 5 strikes, pattern mode Exclude, pattern Automatic import is not possible 50 minutes
Errored 3 strikes 30 minutes
Private torrents ignored

Notes:

  • Don't make the stall and slow rules tight. Torrents with only a few seeds are often slow, not dead. A 3-hour stall limit removes the hopeless ones without hurting slow ones.
  • Failed import with Include and an empty pattern list is rejected. Use Exclude, which acts on every failed import except the patterns you list. Exclude Automatic import is not possible: those downloads finished but Sonarr couldn't match the title to a show, so they only need a manual import (Activity β†’ Queue β†’ Manual Import). Deleting them makes Sonarr grab another release with the same naming problem, again and again.
  • Leave proactive search (Seeker) off unless you want Cleanuparr searching for missing items on its own; it adds load on your indexers. The replacement search after a removal is separate and stays on.
  • Seeding cleanup isn't needed if Transmission already stops seeding at a ratio limit.

Malware Blocker: enable it for Sonarr and Radarr with blocklist type Blacklist and the community list:

https://raw.githubusercontent.com/Cleanuparr/Cleanuparr/main/blacklist

⚠️ Don't use the community blacklist for Lidarr. It is written for video and lists *.flac, *.mp3 and *.m4a, so it marks every file in a music download as unwanted and removes whole albums. Leave the malware blocker off for Lidarr, or give Lidarr its own list.


Step 6: Troubleshooting

  • Check what it did, or would do in Dry Run:
docker logs --since 1h cleanuparr.${HOST_NAME} | grep -i "strike\|removed\|DRY RUN"
  • "Setup required" (HTTP 403) from the API: the admin account hasn't been created yet; see Step 3.
  • Transmission test fails: check the URL base is transmission and that Gluetun is healthy. If Gluetun restarted, recreate Transmission too.
  • An item keeps coming back: the *arr grabbed the same bad release again. Check that the release was blocklisted in the *arr's Activity β†’ Blocklist.
⚠️ **GitHub.com Fallback** ⚠️