unRAID Walkthrough¶

This article will walk you through getting Kometa set up and running via Docker. It will cover:

Installing Kometa unRAID app
Retrieving the image
Setting up the initial config file
Setting up a collection file and creating a couple sample collections
Creating a docker container that will keep running in the background

The specific steps you will be taking:

Verify that Kometa unRAID app is installed and install it if not
Use unRAID APPS to retrieve the Kometa Docker image
Create a directory for your config files and learn how to tell app to use it
Gather two things that the script requires:
1. TMDb API Key
2. Plex URL and Token
Then, iteratively:
1. use unRAID >_Console to run the commands
2. use a text editor to modify a couple of text files until you have a working config file and a single working collection file.

If the idea of editing YAML files by hand is daunting, this may not be the tool for you. All the configuration of Kometa is done via YAML text files, so if you are unable or unwilling to learn how those work, you should stop here.

Finally, this walkthrough is intended to give you a basic grounding in how to get the script running. It doesn't cover how to create your own collections, or how to add overlays, or any of the myriad other things Kometa is capable of. It provides a simple "Getting Started" guide for those for whom the standard install instructions make no sense; presumably because you've never run a unRAID app (Docker container) before.

Prerequisites.¶

Anywhere you see

something like this

That’s a command you’re going to type or paste into your unRAID Kometa >_Console terminal (Linux).

IMPORTANT NOTES:

If you were not aware, the unRAID app store leverages Docker containers. As such, we are tweaking the existing Docker container walkthrough to make it work on unRAID. This walkthrough is going to be pretty pedantic. I’m assuming you’re reading it because you have no idea how to get this going on unRAID, so I’m proceeding from the assumption that you want to be walked through every little detail. You’re going to deliberately cause errors and then fix them as you go through it. This is to help you understand what exactly is going on behind the scenes so that when you see these sorts of problems in the wild you will have some background to understand what’s happening. If I only give you the happy path walkthrough, then when you make a typo later on you’ll have no idea where that typo might be or why it’s breaking things.
You may want to take an hour to get familiar with Docker fundamentals with the official tutorial.
DO NOT MAKE ANY CHANGES BELOW if you want this to just work. Don't change the docker image. linuxserver.io will not work for this, so don't change the paths, etc.

Prepare a small test library [optional]¶

While going through this process, Kometa is going to load the movies in your library, create some collections, and apply some overlays. If you have a large library, this will be very time-consuming.

For learning and testing, you would be well-advised to create a small test library of a reasonable size, where reasonable it probably below a thousand.

The author has a small library of 10 movies that is used for fast tests.

For best results with this walkthrough, your test library will contain:

At least two comedy movies released since 2012.
At least two movies from the IMDB top 250.
At least two movies from IMDb's Popular list.
At least two movies from IMDb's Lowest Rated.
A couple different resolutions among the movies.

That will ensure there's something to go into each of the example collections that will be created.

The advantage of the small test library is that it will reduce the time needed to see results. Running some of these default collections against a library of a few thousand movies can take hours, and for iterative testing it's useful to have something that will run in a few minutes or seconds.

You can set up a test library like this using symlinks without copying files.

Installing Community Applications in unRAID¶

Thankfully, getting Kometa working on unRAID is a fairly simple task. unRAID works mostly with docker containers, so the pre-built container available on docker hub works perfectly with a little configuration. To install a container from docker hub, you will need community applications - a very popular plugin for unRAID servers. If you don't already have this installed, you can install it here

Installing Kometa in unRAID¶

Head to the Apps tab of unRAID (Community Applications), and search kometa in the upper left search box. There will be a couple of results shown, but you should ignore them (Why?) and use the official image.
Click the Install button on the Template from Sohjiro's Repository Tools.
Choose which branch you want to run latest, develop, or nightly.
Set the Console shell command: to Bash
Click Show more settings... to set any Environmental Variables you wish to use. For the purposes of this walkthrough, the Container Path: /config path for the unRAID app is /mnt/user/appdata/Kometa/config (Note the case of Kometa). Other than this, set the KOMETA_TIME variable to 5:00 under the Show more settings...
Hit Apply, and allow unRAID to download the container.

Important note on Docker images¶

This tutorial uses the official image, and you should, too. Don't change kometateam/kometa to the linuxserver.io image or any other. Other images may have idiosyncrasies that will prevent this walkthrough from working. The official image will behave exactly as documented below. Others very possibly won't.

The great thing about Docker is that all the setup you'd have to do to run Kometa is already done inside the docker image.

First let's start the container. Oops! The container won't start? This is going to fail with an error. That's expected.

You should see something like this in the unRAID logs for the container:

Config Error: config not found at //config

We need to have a file called config.yml in the correct directory for Kometa to start. Open up an unRAID terminal session by clicking on the terminal icon >_ in the top right of unRAID.

Linux

[type this into your terminal]

mkdir /mnt/user/appdata/Kometa/config
touch /mnt/user/appdata/Kometa/config/config.yml

You can now close the unRAID terminal and start the Kometa container.

From this point forward, you can Console >_Console into the running container as it will stay running

Open a Console by left-clicking on the running Kometa Container and selecting >_Console. This will open up an interactive session within the container to be able to run the commands we want.

Create a directory to quiet an error later¶

The default config file contains a reference to a directory that will show an error in the output later. That error can safely be ignored, but it causes some confusion with new users from time to time.

We'll create it here so the error doesn't show up later.

Linux

[type this into your terminal]

mkdir config/assets

Setting up the initial config file¶

Next you’ll set up the config file. This tells Kometa how to connect to Plex and a variety of other services.

Before you do this you’ll need:

TMDb API key. They’re free.
Plex URL and Token

There are a bunch of other services you can configure in the config file, but these two are the bare minimum.

Getting a TMDb API Key¶

Note that if you already have an API key, you can use that one. You don’t need another.

Go to https://www.themoviedb.org/. Log into your account [or create one if you don’t have one already], then go to “Settings” under your account menu.

In the sidebar menu on the left, select “API”.

Click to generate a new API key under "Request an API Key". If there is already one there, copy it and go to the next step.

There will be a form to fill out; the answers are arbitrary. The URL can be your personal website, or probably even google.com or the like.

Once you’ve done that there should be an API Key available on this screen. If you see v3 and v4, you want the v3 key.

Copy that value, you’ll need it for the config file.

Getting a Plex URL and Token¶

The Plex URL is whatever URL you’d use from this machine to connect directly to your Plex server [i.e. NOT app.plex.tv].

As with the TMDb API Key, if you already have a Plex Token, you can use that one.

This article will describe how to get a token: Finding an authentication token

Editing the config template¶

First, make a copy of the template:

Linux

Get a copy of the template to edit [type this into your terminal]:

curl -fLvo config/config.yml https://raw.githubusercontent.com/Kometa-Team/Kometa/master/config/config.yml.template

Now open the copy in an editor on the machine of your choice (Use Linux tab below for the Unraid Kometa _>Console):

Linux macOS Windows

[type this into your terminal]

nano config/config.yml

I’m using nano here mostly because it’s simpler than any other editor on Linux.

If you see something like:

 $ nano config/config.yml
zsh: command not found: nano

You need to install nano, which you would do with:

[type this into your terminal]

sudo apt install nano

You can use any other text editor you wish, provided it saves files as PLAIN TEXT. vi, emacs, etc.

[type this into your terminal]

nano config/config.yml

I’m using nano here simply because it’s built into OSX. You can use any other text editor you wish, provided it saves files as PLAIN TEXT. BBedit, TextMate, VSCode, etc.

A common mistake is using TextEdit.app, which saves files as RTF by default.

[type this into your terminal]

notepad .\config\config.yml

I’m using notepad here simply because it’s built into Windows. You can use any other text editor you wish, provided it saves files as PLAIN TEXT.

From here on in, when this walkthrough says "open the config file", I mean this nano or notepad command. Don't copy the template again.

Scroll down a bit and update the three things you just collected; Plex URL, Plex Token, and TMDb API Key.

plex:                                           # Can be individually specified per library as well
  url: http://bing.bang.boing                <<< ENTER YOUR PLEX URL HERE
  token: XXXXXXXXXXXXXXXXXXXX                <<< ENTER YOUR PLEX TOKEN HERE
  timeout: 60
  db_cache:
  clean_bundles: false
  empty_trash: false
  optimize: false
tmdb:
  apikey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX   <<< ENTER YOUR TMDb API KEY HERE
  language: en

Now scroll up and look at the top section:

## This file is a template remove the .template to use the file

libraries:                       # This is called out once within the config.yml file
  Movies:                        # Each library must match the Plex library name
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
    remove_overlays: false       # Set this to true to remove all overlays
    overlay_files:
      - default: ribbon              # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
  TV Shows:
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
    remove_overlays: false       # Set this to true to remove all overlays
    overlay_files:
      - default: ribbon              # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
  Anime:
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: anilist             # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
  Music:
    collection_files:
      - file: config/Music.yml   # This is a local file THAT YOU MIGHT CREATE
playlist_files:
  - default: playlist                # This is a file within Kometa's defaults folder
  # see the wiki for how to use local files, folders, URLs, or files from git

You will ultimately need an entry here for each of the libraries on which you want Kometa to act. Those top-level elements [Movies, TV Shows, Anime, Music] are names of libraries on your Plex server.

For now, delete the “TV Shows”, “Anime”, and "Music" sections from the config file and change the name of the “Movies” section to “Movies-NOSUCHLIBRARY":

The top bit of your config file should now look like this:

libraries:
  Movies-NOSUCHLIBRARY:                         ## <<< CHANGE THIS LINE
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
playlist_files:
  - default: playlist                # This is a file within Kometa's defaults folder
  # see the wiki for how to use local files, folders, URLs, or files from git

This is intended to cause an error for illustration that you will then fix.

Be very careful with the indentation and ensure it looks exactly like the above; each line indented using two spaces, NOT TABS, with playlist_files: all the way over on the left. Indentation is significant in YAML.

Testing the config file¶

Save the file (Use Linux tab below for the Unraid Kometa _>Console):

Linux macOS Windows

If you're using nano, type control-x, then y, then the enter key.

If you're using notepad, type control-s or choose Save from the File menu.

Then run the script again:

[type this into your terminal]

python kometa.py -r

I’ve removed some of the lines for space, but have left the important bits:

...
|                                            Starting Run|
...
| Locating config...
|
| Using /Users/mroche/Kometa/config/config.yml as config
...
| Connecting to TMDb...
| TMDb Connection Successful
...
| Connecting to Plex Libraries...
...
| Connecting to Movies-NOSUCHLIBRARY Library...                                                      |
...
| Plex Error: Plex Library Movies-NOSUCHLIBRARY not found                                            |
| Movies-NOSUCHLIBRARY Library Connection Failed                                                     |
|====================================================================================================|
| Plex Error: No Plex libraries were connected to                                                    |
...

You can see there that Kometa found its config file, was able to connect to TMDb, was able to connect to Plex, and then failed trying to read the “Movies-NOSUCHLIBRARY" library, which of course doesn’t exist.

Open the config file again and change "Movies-NOSUCHLIBRARY" to reflect your own Movie library in Plex.

Say my Movies library is called “All The Movies", so mine looks like this:

libraries:
  All The Movies:                            ## <<< CHANGE THIS LINE
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git

At this point, the top bit of your config file should look like this:

libraries:
  THE_NAME_OF_YOUR_MOVIE_LIBRARY:         ## <<< CHANGE THIS LINE
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
playlist_files:
  - default: playlist                # This is a file within Kometa's defaults folder
  # see the wiki for how to use local files, folders, URLs, or files from git

Where THE_NAME_OF_YOUR_MOVIE_LIBRARY has been replaced by the name of your movie library as shown in Plex ["All The Movies" here]:

Creating a few sample collections.¶

Kometa provides an extensive collection of "default" collection files.

These files provide a simple way for you to create collections based on franchises or awards or actors, etc.

The default config links to two of them, these two lines in your config file:

libraries:
  THE_NAME_OF_YOUR_MOVIE_LIBRARY:
    collection_files:
      - default: basic               # <<< THIS LINE
      - default: imdb                # <<< THIS LINE
playlist_files:
  - default: playlist

The first will create:

Newly Released
New Episodes [TV libraries only]

The second will create:

IMDb Popular
IMDb Top 250
IMDb Lowest Rated

So let's run the script and see this happen:

[type this into your terminal]

python kometa.py -r

Depending on the size of the library, this may take a while.

As it builds the collections, you should see a fair amount of logging about which movies are being added and which ones aren’t found. Once it completes, go to Plex, go to your Movies library, and click “Collections” at the top.

On my test library, this created four collections. You may see fewer depending on what specific movies are in that library.

Perhaps you can do everything you want in terms of collections [award collections, actor collections, genre collections, franchise collections, etc] with the defaults. You can investigate what they can provide under the "Defaults" heading at the top of this wiki.

Setting up a collection file and creating a sample collection.¶

(Use Linux tab below for the Unraid Kometa _>Console):

If the default collection files do not allow you to create the collections you want, you can define your own collections in your own collection files to do whatever you like within the capabilities of Kometa. We will create a simple collection that will contain 20 comedy movies released since 2012.

First, open the collection file [this will create the file if it doesn't already exist]:

Linux macOS Windows

[type this into your terminal]

nano "config/Movies.yml"

[type this into your terminal]

nano "config/Movies.yml"

[type this into your terminal]

notepad "config\Movies.yml"

In this file, add the following, exactly as it is shown here; remember that spacing is significant in YAML files:

collections:
  Recent Comedy:
    plex_search:
      all:
        genre: Comedy
        year.gte: 2012
      limit: 20

Save the file:

Linux macOS Windows

If you're using nano, type control-x, then y, then the enter key.

If you're using notepad, type control-s or choose Save from the File menu.

Next, add a reference to this file to your config file.

Open the config file again and add the last line shown below:

libraries:
  All The Movies:
    collection_files:
      - default: basic
      - default: imdb
      # see the wiki for how to use local files, folders, URLs, or files from git
      - file: config/Movies.yml     ## <<< ADD THIS LINE

That line needs to match the path you used when you created the file a moment ago. If you are copy-pasting these commands, it does.

Save the file (Use Linux tab below for the Unraid Kometa _>Console):

Linux macOS Windows

If you're using nano, type control-x, then y, then the enter key.

If you're using notepad, type control-s or choose Save from the File menu.

Then run the script again:

[type this into your terminal]

python kometa.py -r

You should see that the collection file gets loaded:

| Loading Collection File: config/Movies.yml
| Collection File Loaded Successfully

As it builds the collection, you should see a fair amount of logging about which movies are being added and which ones aren’t found. Once it completes, go to Plex, go to your Movies library, and click “Collections” at the top.

You should see the new collection:

When you click into each, you’ll see the movies that Kometa added to each collection.

Each time you run the script, new movies that match the collection definitions will be added. For example, if you don’t have “The ShawShank Redemption” now, when you download it and run Kometa again it will be added to the IMDB 250 collection.

Adding Overlays to movies.¶

The default collection files include a set of overlays you can add to your posters.

We'll add resolution overlays to the movies in this library as an example.

Open the config file again and add the last three lines shown below:

libraries:
  All The Movies:
    collection_files:
      - default: basic               # This is a file within the defaults folder in the Repository
      - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
      - file: config/Movies.yml
    remove_overlays: false            ## <<< ADD THIS LINE
    overlay_files:                         ## <<< ADD THIS LINE
      - default: resolution                   ## <<< ADD THIS LINE

Save the file (Use Linux tab below for the Unraid Kometa _>Console):

Linux macOS Windows

If you're using nano, type control-x, then y, then the enter key.

If you're using notepad, type control-s or choose Save from the File menu.

Then run the script again:

[type this into your terminal]

python kometa.py -r

While it runs this time you should see the previous collections go by pretty quickly, since they aren't changing, and then a lot of logging as Kometa decides which overlays apply to which movies.

This may take quite a while depending on the size of this library.

Eventually, you'll see it start applying overlays to all your movies:

|=========================================================|
|    Applying Overlays for the All The Movies Library     |
|=========================================================|
|                                                         |
| 10 Cloverfield Lane         | Overlays Applied: 4K-HDR  |
| 10 Minutes Gone             | Overlays Applied: 4K-HDR  |
| 10 Things I Hate About You  | Overlays Applied: 4K-HDR  |
| 12 Mighty Orphans           | Overlays Applied: 4K-HDR  |
| 12 Monkeys                  | Overlays Applied: 4K-DV   |
| 12 Strong                   | Overlays Applied: 4K-HDR  |
...

When it finishes, go to the Library tab in this library in Plex:

What comes next:¶

If you want to remove those overlays, open the config file, change the value of remove_overlays to true, and rerun Kometa.

    remove_overlays: true
    overlay_files:
      - default: resolution

If you want to remove those collections, open the config file, remove or comment out [add # to the beginning] any or all of those lines under collection_files, and delete the collections manually from Plex.

libraries:
  All The Movies:
    collection_files:
      # - default: basic               # This is a file within the defaults folder in the Repository
      # - default: imdb                # This is a file within the defaults folder in the Repository
      # see the wiki for how to use local files, folders, URLs, or files from git
      # - file: config/Movies.yml
    remove_overlays: false
    overlay_files:
      - default: resolution

Edit Movies.yml to reflect the actions you want Kometa to perform on your libraries.

TV Shows and other libraries work the same way as you've seen above. Create a section under libraries: in the config.yml, refer to default files or create a collection file, define collections, run the script.

Investigate the rest of the wiki to learn about everything Kometa can do for you.

Runtime and Environment Flags¶

The command in this walkthrough will run all collections and libraries immediately. If you want to modify that behavior to run just one or some collections, or just one library, or just overlays or the like, review the Run Commands & Environment Variables.

Creating Collections, Overlays, Playlists, etc.¶

These things are all generally defined in collection files that are referred to in the config file. The starting point for creating these files is here.

unRAID Walkthrough¶

Prerequisites.¶

Prepare a small test library [optional]¶

Installing Community Applications in unRAID¶

Installing Kometa in unRAID¶

Important note on Docker images¶

Create a directory to quiet an error later¶

Setting up the initial config file¶

Getting a TMDb API Key¶

Getting a Plex URL and Token¶

Editing the config template¶

Testing the config file¶

Creating a few sample collections.¶

Setting up a collection file and creating a sample collection.¶

Adding Overlays to movies.¶

What comes next:¶

Runtime and Environment Flags¶

Creating Collections, Overlays, Playlists, etc.¶

Other Topics¶

Scheduling¶

I want to use the develop branch¶

I want to use the nightly branch¶

I want to ensure I am using the master branch¶