Repository navigation
Kometa Setup Guide
Kometa (formerly Plex Meta Manager) builds and maintains collections in Plex automatically: franchises in watch order, "Trending this week", Oscar winners, Christmas movies in December, and so on. It can also add overlays (badges) to posters, such as resolution, HDR or Rotten Tomatoes scores, so you see them while browsing instead of opening each title.
It's most valuable when your household browses Plex rather than searching.
Read this first: protect your Plex database. Kometa makes thousands of changes through Plex's API. A heavy first run (every library, overlays and playlists at once) on a slow NAS can corrupt Plex's database badly enough that it can't be recovered, and rebuilding it loses everyone's watch history. Start small, back up first, and grow one step at a time. The steps below are built around that.
-
Runs on a desktop, not the NAS (
compose/server2/kometa.yaml). Kometa talks to Plex over the network, and the heavy part (building overlay images) uses that machine's CPU. - Runs at 00:30, finishing before Plex's own nightly maintenance (from 02:00), so the two never write to the database at the same time.
- If that machine is off, that night's run is skipped; collections stay as they are.
services:
kometa:
container_name: kometa.${HOST_NAME}
image: kometateam/kometa:latest
environment:
TZ: ${TZ}
KOMETA_TIMES: "00:30" # run time(s); Kometa ignores CRON
KOMETA_CONFIG: /config/config.yml
volumes:
- ${DOCKERDIR}/kometa/config:/config
restart: unless-stoppedPlex keeps its own backups (Settings → Scheduled Tasks → Backup database every three days; leave it on). Before Kometa's first run, and before each big step up, also make a copy you know is good, using Plex's bundled SQLite while Plex is running:
docker exec plex.<host> sh -c '
cd "/config/Plex Media Server/Plug-in Support/Databases"
S="/usr/lib/plexmediaserver/Plex SQLite"
for db in com.plexapp.plugins.library.db com.plexapp.plugins.library.blobs.db; do
"$S" "$db" ".backup \"$db-before-kometa\""
"$S" "$db-before-kometa" "PRAGMA quick_check;" # should print: ok
done'(The path inside the container depends on your Plex image.)
appdata/kometa/config/config.yml (keep it out of git; it holds your Plex token and TMDb key):
plex:
url: http://192.168.1.10:32400
token: <your Plex token>
tmdb:
apikey: <free key from themoviedb.org>
language: en
libraries:
Movies:
collection_files:
- default: basic # Newly Released, Recently Added
- default: tmdb # Trending, Popular, Top Rated
- default: imdb # IMDb Top 250, Popular
- default: franchise # franchises in release order
- default: seasonal # Christmas, Halloween... shown in season
- default: decade
- default: oscars
settings:
run_order:
- collections
cache: true
sync_mode: append
minimum_items: 1
delete_below_minimum: trueStart with one library and collections only: no overlay_files, no playlist_files, no operations.
A test run connects to Plex and TMDb and checks the config, but only builds collections marked test: true (none, here):
docker compose -p mediaserver -f docker-compose-server2.yaml run --rm kometa --run --testsLook for TMDb Connection Successful and Movies Library Connection Successful.
On the very first run you'll see thousands of No TMDb ID for Guid: plex://movie/... lines. That's normal: they appear before Kometa has built its ID cache, and later in the same run it matches the movies (Cache | + | plex://movie/... | TMDb ID: ...). From then on the cache is used.
Then leave it to its schedule, and read the log after the first night: appdata/kometa/config/logs/meta.log.
After a few clean nights, add one thing at a time, backing up the database before each:
-
Rotten Tomatoes scores on posters (critic and audience):
Overlays replace each poster with a badged version. Kometa keeps the original so
overlay_files: - default: ratings template_variables: rating1: critic rating1_image: rt_tomato rating2: audience rating2_image: rt_popcorn
remove_overlays: truecan put it back. - TV collections, then TV overlays.
- Other libraries (animated, music) last.
-
Connection refusedto Plex: use the server's LAN IP and port 32400, not a domain behind Cloudflare Access. - Run takes hours: that's usually overlays on a big library; keep them to the libraries where you want them.
-
Collections disappeared:
delete_below_minimum: trueremoves collections that drop belowminimum_items, and seasonal collections hide out of season. Both are expected. - Plex feels slow during the run: move the run time further from busy hours, and keep it out of Plex's maintenance window.