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/jorenn92/maintainerr:latest
    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

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** ⚠️