Plex-Meta-Manager/docs/kometa/install/getting_started.md

Getting Started with Kometa

Kometa has a relatively simple startup process. This guide will walk you through the things you have to do to get started with Kometa.

Typical startup problems

Generally, the most common problems that users encounter when starting Kometa are related to finding some complicated config and copy-pasting it without understanding it, or trying to add a whole lot of things at once, again without understanding how the tool works.

The key is to start slow and simple, and build up from there. Don't get impatient and try to add everything at once. You'll get there, but it's better to start with a simple setup and build up from there.

An imperfect metaphor would be: "Hey, changing my oil was fun. I think I'll rebuild the engine next!"

There is a four-hour video that gets a lot of attention and gets held up as evidence that Kometa takes four hours to set up. This is not true. The video is a deep dive into the creator's complicated setup that is specific to his requirements. It starts by setting up a third-party script [written by one of the Kometa team] describing it as a requirement even before installing Kometa. This script is not required by Kometa in any way. In any case, the Kometa setup is not a four-hour process. The setup process is actually quite simple.

From a standing start, you can have Kometa up and running in maybe 10 minutes.

Of course, tuning and tweaking and adding more libraries and more features will take longer, perhaps four hours or more, but the basic setup is quite simple.

Required steps

There are two required steps:

1. Install Kometa
2. Create a config file

Step 1: Install Kometa

You can run Kometa in one of two ways: running as a Python script on your system, or running as a Docker container.

Running as a Docker container is generally simpler, as you won't have to be concerned about installing Python, or support libraries, or any possible system conflicts generated by those actions.

There is really not much of an "install" process for Kometa. You will either download some files into a directory and run a script, or you will pull a Docker image and run a container.

You may need to install Python or Docker, but that's not a Kometa-specific requirement.

The Kometa files themselves are self-contained and do not require any installation process beyond downloading them.

Similarly, the docker image is self-contained and does not require any installation process beyond pulling the image.

Step 2: Create a config file

There are two platform-independent walkthroughs for getting started with Kometa:

1. Local Python script
2. Docker container

Both of those walkthroughs will get you up and running with Kometa in a few minutes using mostly copy-paste commands. They will take you through:

- Setting up the initial config file
- Creating some sample collections using the defaults
- Setting up a collection file and creating a sample collection
- Adding some default overlays

After you complete the steps in one of those walkthroughs, you will have a working Kometa setup, ready for you to tune and expand.

Those walkthroughs don't cover my NAS

That same config file can be used on any platform or NAS; you don't need to create a new one for each platform.

The walkthrough can be completed on any platform, regardless of where you plan to run Kometa. For example, if you plan to run Kometa on a NAS like a Synology or what have you, you can complete the walkthrough on your Windows or MacOS system, and then copy the config file to the NAS. You may need to adjust a path or two in the config file, and perhaps change the Plex/Radarr/Sonarr/Tautulli URLs if they need to be addressed differently from a container on the NAS, but otherwise the config file is portable.

Docker is Docker, and conceptually the same [at this level] on any platform. If you are using the docker command line, the commands to pull the image and run the container are the same on any platform. The only difference is the path to the config file, which you will need to adjust.

The GUI for creating a docker container will differ from NAS to NAS, and there's no way for this documentation to cover any and all variations, but the basic steps are the same:

1. create container from the official image
2. map a local directory to the container at /config
3. put a config.yml file in that directory

Those steps are the same on any platform, though the things you need click may vary. Any NAS that can run a docker container can do those three things; none of them are unique to Kometa.

There's so much in this config file

There is. Kometa is a powerful tool with a lot of features. But you don't need to understand all of them to get started. You can start with a simple config file and build up from there.

The absolute minimum config file is just a few lines. You can add more features as you learn about them and as you need them.

Minimal config.yml

Here's the absolute minimum config.yml file you need to get started:

libraries:
  NAME_OF_YOUR_MOVIE_LIBRARY
    collection_files:
      - default: basic
 
plex:
  url: YOUR_PLEX_URL
  token: YOUR_PLEX_TOKEN

tmdb:
  apikey: YOUR_TMDB_API_KEY

Change those four UPPER_CASE items to your actual values, and you're good to go. Running that file will create a couple of collections in your Plex library.

Kometa will also fill in that file with a lot of defaults, ready for you to modify and expand as you learn more about Kometa. It does this so that as new settings are added, the default values are inserted into your config file, ready for you to modify.

Once you have Kometa set up and are actively making changes, most of your changes will happen under the libraries section of the config file. Most. Not "all", most. There are of course changes you can and may want to do elsewhere to support your requirements, but the vast majority of your work will be in the libraries section.

Start slow and build up

The single most common mistake most new users make is trying to add everything at once. They see the power of Kometa and want to use all of it right away. This is a recipe for frustration.

Start slow. Start simple. Add a feature or two at a time. Learn how they work. Understand how they interact with each other. Then add more features.

There's a config floating around from bullmoose20 that a lot of people decide to start with. You don't need to start with that. You SHOULDN'T start with that. That config will take hours if not days to run on nearly any system against nearly any library. It's a complex config that is meant to show off the power of Kometa, not to be a starting point.

You can start with the minimal config above and build up from there.

Another common mistake is finding some config on Reddit or elsewhere and just copy-pasting the whole thing, or worse, chunks of the whole thing, into your config file. This is a recipe for disaster. Probably, you don't know what all those settings do, and you don't know how they interact with each other. Then you're going to search for things in the wiki and find stuff out of context, copy-paste those things, and still have problems. You're going to have a bad time.

I know it's boring and you want the cool stuff now, but trust me. Start slow. Start simple. Build up from there.

Kometa is, for better or worse, a very technical tool and requires a certain amount of technical knowledge to use. You don't need to be a programmer, but you do need to be able to read and understand the documentation, and you do need to be able to understand how the tool works.

Next steps

So you have a working config file. What now?

Defaults

Perhaps you want to explore the collections and overlays that Kometa provides as part of the defaults. If you want to create a variety of collections with a minimum of fuss, these are for you. They can be enabled in your config with a single line, and support limited customization via "template_variables" in the config file.

For example, this will create 7 Academy Award collections, "Best Picture" (all years), "Best Director" (all years), and yearly collections for the past five years.

libraries:
  Movies:
    collection_files:
      - default: oscars

If you wanted to create yearly collections for the past ten years, you could do that with:

libraries:
  Movies:
    collection_files:
      - default: oscars
        template_variables:
          data:
           starting: latest-11

All of the defaults work this way. You can enable them with a single line, and customize them with template_variables.

The defaults are all documented starting here.

Custom Collections/Overlays/Metadata

If the defaults don't meet your needs, you can create your own external YAML files to define your own collections, overlays, and metadata. These files can be as simple or as complex as you need them to be.

The various types of external YAML files are discussed starting here.

Community configs

There are a variety of configs supplied by the community in the community configs repo.

IMPORTANT: These configs are not supported by the Kometa team. They are provided by the community, and you should use them at your own risk. They are not guaranteed to work, and they may not be up to date with the latest changes in Kometa.

You can find the community configs here. When you visit, note that the last modified dates on most of them are years ago. They may not work with the current version of Kometa.