Kometa Integration

Kometa Integration

CHUB and Kometa are designed to work together: Kometa manages Plex metadata and collections, CHUB manages the poster files and media chores that feed them. poster_renamerr specifically reads Kometa's asset output so your renamed posters land in the right places.

This page covers the one-time setup so the two tools see the same world.

---

📐 The setup in one picture

  ┌─────────────────────┐       ┌─────────────────────┐       ┌─────────────────────┐
  │      Kometa         │       │       CHUB          │       │       Plex          │
  │                     │       │                     │       │                     │
  │  writes posters to  │─────▶ │  poster_renamerr    │─────▶ │  applies posters to │
  │  its asset folder   │       │  renames + copies   │       │  library items      │
  └─────────────────────┘       └─────────────────────┘       └─────────────────────┘

• Kometa writes original posters to its asset_directory.
• CHUB's poster_renamerr reads from that directory, matches each poster against your ARR / Plex libraries, renames the files, and copies/moves/hardlinks them into your destination_dir.
• Plex picks the renamed posters up (optionally pushed directly via the Plex API when you enable add_posters).

---

🔧 Kometa side

In your Kometa config.yml, make sure asset folders are enabled:

settings:
  asset_directory:
    - /config/assets            # where Kometa drops posters
  asset_folders: true           # one folder per item: Movie (2020)/poster.jpg
  asset_depth: 0

Key points:

• asset_folders: true is required. CHUB's poster_renamerr extracts title, year, and tmdb_id/tvdb_id/imdb_id from the folder and the filename, so a per-item folder improves matching accuracy a lot.
• asset_directory can be a list. CHUB can read from multiple.

---

🐳 Docker mount alignment

CHUB's container needs to read the same folder Kometa writes to. In your CHUB compose.yaml:

services:
  chub:
    volumes:
      - /srv/kometa/assets:/kometa        # Kometa's asset_directory, mounted into CHUB
      - /srv/apps/chub/posters:/posters   # CHUB's destination_dir

If Kometa writes to /srv/kometa/assets on the host, CHUB sees it at /kometa inside its container.

Permissions: CHUB's PUID/PGID must be able to read the Kometa folder. If Kometa writes as 1000:1000 and CHUB runs as 99:100 (Unraid defaults), CHUB won't be able to open the files. Either align the UIDs or run both containers with the same PUID/PGID.

Read/write: if you set poster_renamerr.action_type to move, CHUB removes the file from the Kometa folder after renaming. For copy or hardlink, read access is enough.

---

⚙️ CHUB side

In CHUB's config.yml (or Settings → Modules → poster_renamerr):

poster_renamerr:
  source_dirs: [/kometa]           # matches the mount above
  destination_dir: /posters        # where renamed copies land
  action_type: hardlink            # copy | move | hardlink
  asset_folders: true              # expects per-item folders, matches Kometa
  instances:
    - radarr_main
    - sonarr_main
    - plex_main:
        library_names: ["Movies", "TV Shows"]
        add_posters: true          # push straight into Plex via the API

Key points:

• source_dirs = the in-container path of your Kometa asset volume.
• asset_folders: true must match your Kometa setting.
• action_type: hardlink is the cheapest — no extra disk use, both trees point at the same inode. Source and destination must be on the same filesystem.
• add_posters: true on Plex instances pushes the renamed poster directly via the Plex API after CHUB copies it into destination_dir. Without it, Plex only picks up posters if it's scanning the folder.

---

✅ Verifying it works

1. Run Kometa once so it writes a few items to asset_directory.
2. In CHUB, go to Dashboard → New run → poster_renamerr with dry_run: true and click Run.
3. Open the run log — you should see per-item match attempts and proposed rename paths. No files are touched in dry-run mode.
4. Turn dry_run off and run again. Files show up in destination_dir with ARR/Plex-friendly names.

If poster_renamerr reports "No matching ARR items", enable debug log level and look at the match attempts — usually it means an ID is missing from the filename and the folder, or the Kometa folder doesn't follow the Movie (2020) / Series (2020) naming convention.

---

Related

• Modules → poster_renamerr
• Configuration
• Troubleshooting → poster_renamerr runs but nothing moves