Maintainerr Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Maintainerr Setup Guide

Introduction

Maintainerr is an automated media cleanup tool that integrates with Plex, Sonarr, Radarr, and Seerr/Overseerr. It uses rule-based logic to identify stale or unwatched content and supports dry-run auditing, tagging, and safe deletion workflows.


Step 1: Initial Container Deployment

  1. Copy the maintainerr.yaml template into your active server compose directory:
cp compose/templates/maintainerr.yaml compose/server1/maintainerr.yaml
  1. Ensure your root .env includes your designated port setting:
MAINTAINERR_PORT=6246
  1. Create host storage directories and set proper non-root ownership permissions (1000:100 or your host user UID:GID):
sudo mkdir -p ${DOCKERDIR}/maintainerr/data ${DOCKERDIR}/logs/maintainerr
sudo chown -R 1000:100 ${DOCKERDIR}/maintainerr ${DOCKERDIR}/logs/maintainerr
  1. Launch the container:
docker compose -p mediaserver -f docker-compose-server1.yaml up -d maintainerr

⚠️ Important Permission Notice: Set PUID and PGID to match a valid user/group on the host. Run id <your-user> to confirm, and chown -R the mounted volumes accordingly. Maintainerr v2+ does not run as root and will crash-loop without proper volume permissions.


Step 2: Service Definition (maintainerr.yaml)

# Maintainerr - Automated media cleanup and maintenance
services:
  maintainerr:
    container_name: maintainerr.${HOST_NAME}
    hostname: maintainerr.${HOST_NAME}.lan
    image: ghcr.io/maintainerr/maintainerr:latest  # moved from ghcr.io/jorenn92 in 2025
    environment:
      PUID: ${PUID}
      PGID: ${PGID}
      TZ: ${TZ}
      DOMAINNAME: ${DOMAINNAME}
      HOST_NAME: ${HOST_NAME}.lan
    networks:
      - mediaserver
    ports:
      - "${MAINTAINERR_PORT}:6246"
    volumes:
      - ${DOCKERDIR}/maintainerr/data:/opt/data
      - ${DOCKERDIR}/logs/maintainerr:/var/log
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=Media"
      - "homepage.name=Maintainerr"
      - "homepage.icon=maintainerr.png"
      - "homepage.href=https://maintainerr.${DOMAINNAME}/"
      - "homepage.description=Automated media cleanup and maintenance"

Step 3: Accessing the UI

  1. Open your browser and navigate to http://<your-ip-address>:6246.
  2. Authenticate with your credentials if enabled.
  3. Navigate to Settings to begin integration setup.

Step 4: Integrations Setup

Maintainerr supports direct integration with your media stack. Ensure all services are connected and authenticated.

📺 Plex Integration

  1. Go to Settings -> Plex.
  2. Enter your Plex server IP/hostname and port (32400).
  3. Paste your Plex token (found via Settings -> Account -> Show Advanced).
  4. Click Test Connection then Save.

Maintainerr Plex Setup


🎬 Radarr Integration

  1. Go to Settings -> Radarr.
  2. Enter your Radarr host, port (7878), and API key.
  3. Click Test Connection then Save.

Maintainerr Radarr Setup


📺 Sonarr Integration

  1. Go to Settings -> Sonarr.
  2. Enter your Sonarr host, port (8989), and API key.
  3. Click Test Connection then Save.

Maintainerr Sonarr Setup


📥 Overseerr / Seerr Integration

  1. Go to Settings -> Overseerr.
  2. Enter your Seerr/Overseerr host, port (5055), and API key.
  3. Click Test Connection then Save.

Maintainerr Overseerr Setup


📊 Tautulli Integration (Optional)

  1. Go to Settings -> Tautulli.
  2. Enter your Tautulli host, port (8181), and API key.
  3. Click Test Connection then Save.

Maintainerr Tautulli Setup


🔔 Notifications

  1. Go to Settings -> Notifications.
  2. Choose your preferred service (e.g., Discord, Telegram, Gotify).
  3. Enter webhook or token details.
  4. Click Test Notification then Save.

Maintainerr Notifications


Step 5: Rule & Tag Configuration

Lessons learned (2026):

  • Image moved: Maintainerr now publishes to ghcr.io/maintainerr/maintainerr. The old ghcr.io/jorenn92/maintainerr stopped getting updates.
  • Pick "Delete" as the Radarr/Sonarr action. "Unmonitor and delete files" leaves the movie listed in Radarr (and an empty folder on disk) forever. "Delete" removes it from Radarr/Sonarr, and they remove the folder too, so no leftovers build up.
  • Think twice about "Add to list exclusions". Exclusions stop import lists from adding the title again, but they also get in the way when someone requests it later through Seerr. This repository leaves them off.
  • Protect anything tagged save in every rule section, including list-import clean-up rules, with "Tags does not contain save". Tag your keepers (classics, family favourites) in Radarr/Sonarr.
  • Use Radarr's "Date added" for list imports. Movies added by import lists were never requested in Seerr, so a rule based on the Seerr request date never matches them.
  • Folders Radarr doesn't know about are invisible to Maintainerr. If the log shows many Could not find Movie with TMDb id warnings, see "Adopting existing movie folders" in Radarr Setup Guide.

Navigate to Rules in the left menu.

Tags Setup in Radarr / Sonarr

You can add tags in Radarr or Sonarr to ensure media is protected or included in rules:

  • Use list-import for items imported from lists (add to your Import List settings).
  • Use save to protect specific items from deletion.

Sonarr Save Tag Radarr List Import Tag


Rule Definition: TV Shows Ruleset

Maintainerr TV Rules

mediaType: SHOWS
rules:
  - "0":
      - firstValue: Overseerr.isRequested
        action: EQUALS
        customValue:
          type: boolean
          value: "true"
      - operator: AND
        firstValue: Sonarr.tags
        action: NOT_CONTAINS_PARTIAL
        customValue:
          type: text
          value: save
  - "1":
      - firstValue: Overseerr.isRequested
        action: EQUALS
        customValue:
          type: boolean
          value: "true"
      - operator: AND
        firstValue: Sonarr.status
        action: EQUALS
        customValue:
          type: text
          value: ended
      - operator: AND
        firstValue: Plex.sw_allEpisodesSeenBy
        action: CONTAINS
        lastValue: Overseerr.addUser
      - operator: AND
        firstValue: Plex.sw_lastWatched
        action: BEFORE
        customValue:
          type: custom_days
          value: "182"
  - "2":
      - firstValue: Overseerr.isRequested
        action: EQUALS
        customValue:
          type: boolean
          value: "true"
      - operator: AND
        firstValue: Plex.sw_viewedEpisodes
        action: EQUALS
        customValue:
          type: number
          value: 0
      - operator: AND
        firstValue: Plex.sw_lastEpisodeAddedAt
        action: BEFORE
        customValue:
          type: custom_days
          value: "182"

Rule Definition: Movies Ruleset

Maintainerr Movies Rules

mediaType: MOVIES
rules:
  - "0":
      - firstValue: Overseerr.isRequested
        action: EQUALS
        customValue:
          type: boolean
          value: "true"
      - operator: AND
        firstValue: Plex.seenBy
        action: CONTAINS
        lastValue: Overseerr.addUser
      - operator: AND
        firstValue: Plex.lastViewedAt
        action: BEFORE
        customValue:
          type: custom_days
          value: "182"
      - operator: AND
        firstValue: Radarr.tags
        action: NOT_CONTAINS_PARTIAL
        customValue:
          type: text
          value: save
  - "1":
      - operator: OR
        firstValue: Overseerr.isRequested
        action: EQUALS
        customValue:
          type: boolean
          value: "true"
      - operator: AND
        firstValue: Plex.viewCount
        action: EQUALS
        customValue:
          type: number
          value: 0
      - operator: AND
        firstValue: Plex.addDate
        action: BEFORE
        customValue:
          type: custom_days
          value: "730"
      - operator: AND
        firstValue: Radarr.tags
        action: NOT_CONTAINS_PARTIAL
        customValue:
          type: text
          value: save
  - "2":
      - operator: OR
        firstValue: Radarr.tags
        action: CONTAINS
        customValue:
          type: text
          value: list-import
      - operator: AND
        firstValue: Plex.viewCount
        action: EQUALS
        customValue:
          type: number
          value: 0
      - operator: AND
        firstValue: Radarr.addDate
        action: BEFORE
        customValue:
          type: custom_days
          value: "730"
      - operator: OR
        firstValue: Plex.addDate
        action: BEFORE
        customValue:
          type: custom_days
          value: "730"
      - operator: AND
        firstValue: Radarr.tags
        action: NOT_CONTAINS_PARTIAL
        customValue:
          type: text
          value: save
  - "3":
      - operator: OR
        firstValue: Radarr.tags
        action: CONTAINS
        customValue:
          type: text
          value: list-import
      - operator: AND
        firstValue: Plex.lastViewedAt
        action: BEFORE
        customValue:
          type: custom_days
          value: "730"
      - operator: AND
        firstValue: Radarr.tags
        action: NOT_CONTAINS_PARTIAL
        customValue:
          type: text
          value: save

Step 6: Job Scheduling

Use cron expressions in Maintainerr settings to control execution times:

Job Type Cron Expression Description
Rule Handler 0 3 * * * Identifies media matching rules overnight
Collection Handler 0 4 * * * Processes collections & safe deletions

Step 7: Backup and Restore Procedures

Regular Backups

  • Back up ${DOCKERDIR}/maintainerr/data and ${DOCKERDIR}/logs/maintainerr periodically.
  • Ensure maintainerr.db and config.yaml are included.

Restoration Process

  1. Deploy a new container using maintainerr.yaml.
  2. Copy backup files into the data folder:
    sudo cp /path/to/backup/config.yaml ${DOCKERDIR}/maintainerr/data/config.yaml  
    sudo cp /path/to/backup/maintainerr.db ${DOCKERDIR}/maintainerr/data/maintainerr.db
  3. Restart the container and verify rule integrity.

Step 8: Management & Troubleshooting

  • Dry-run first: Test rules in Maintainerr before enabling live deletion.
  • Logs: Check ${DOCKERDIR}/logs/maintainerr for rule execution and errors.
  • Permissions: Double-check UID/GID permissions if the container crashes on startup.
⚠️ **GitHub.com Fallback** ⚠️