The word "run" in the Kometa context can be used in two ways; you "run" the Kometa Python script itself, using a Python or docker command, and then that script behaves in one of two ways:
1. It sits and waits until a particular time, wakes up and processes the config file, then goes back to sleep until that same time the next day. Kometa does this unless you [specifically tell it to do otherwise](#run).
2. It processes the config file right away and then exits.
"Processes the config file" means that it will go through all the collections, metadata, overlays, playlists, and libraries that you have defined in your config file and do what you have told it to do with them.
That's kind of a mouthful, though, so we typically use "run" to describe that bit of the process.
In these docs, and in the discord when providing support, we'll use "run" to describe the "process the config file" bit.
The basic command to execute Kometa is as follows:
=== "Windows / Mac / Linux"
@ -15,20 +29,74 @@ The basic command to run Kometa is as follows:
docker run --rm -it -v "/<ROOT_KOMETA_DIRECTORY_HERE>/config:/config:rw" kometateam/kometa
```
To customize the running of Kometa according to your needs, you can use either run commands or environmental
variables. Environmental variables take precedence over run command attributes. However, if you encounter a race
condition where an attribute has been set both via an environmental variable and a shell command, the environmental
variable will be given priority.
As discussed above, that will start Kometa, which will then wait until 5AM to wake up and process the config file.
The basic command to execute Kometa, telling it to run right this second, is as follows:
=== "Windows / Mac / Linux"
``` py
python kometa.py --run
```
=== "Docker"
``` py
docker run --rm -it -v "/<ROOT_KOMETA_DIRECTORY_HERE>/config:/config:rw" kometateam/kometa --run
If you want to modify the way Kometa behaves when it runs, you can use the commands on this page. None of these are *required* to run Kometa. They are all optional and can be used to customize the way Kometa runs to suit your needs.
Many of these override settings in the config file, so you can use them to change the way Kometa behaves without having to edit the config file.
Please note that these instructions assume that you have a basic understanding of Docker concepts. If you need to
familiarize yourself with Docker, you can check out the official tutorial.
You can set any of these flags as either environment variables or as command line arguments.
Another way to specify environmental variables is by adding them to a .env file located in your config folder.
On all platforms, "environment variables" are a way to set variables that are available to all programs running on the system. You can set these variables in your shell, in a script, or in a Docker container.
Environment variables are expressed as `KEY=VALUE` depending on the context where you are specifying them, you may enter
those two things in two different fields, or some other way. The examples below show how you would specify the
environment variable in a script or a `docker run` command. Things like Portainer or a NAS Docker UI will have
different ways to specify these things.
You might think of this as a note on your desk that tells you Sue likes a skim latte when you go to the coffee shop. You can use that note to remember what Sue likes when she asks "please get me a coffee".
Runtime flags are command line arguments that you can pass to Kometa when you run it to change the way it behaves.
You might think of this as a directive Bob adds when he asks "please get me a coffee, a **flat white**". At "runtime", Bob is adding a "flag" to his request to indicate the type of coffee.
All these settings have defaults, which you can think of as the "standard coffee" that you get if someone doesn't specify anything. If Chris doesn't specify a type of coffee, and you have no note about Chris, Chris gets the **default**, a **plain black coffee**.
If you don't specify a runtime flag or environment variable, you get the standard/default behavior.
## Runtime Flags vs Environment Variables; who wins?
The ridiculous example above notwithstanding, in Kometa, environment variables take precedence over runtime flags.
For example, and it's not important what this does, but if you were to use the following script:
```shell
export KOMETA_CONFIG=/path/to/environment/config.yml # this sets an environment variable
python kometa.py --config /path/to/runtime-var/config.yml # runtime flag for the same setting
```
Kometa would use the config file at `/path/to/environment/config.yml` because the environment variable takes precedence over the runtime flag.
Please note that these instructions assume that you have a basic understanding of command line and Docker concepts. If you need to familiarize yourself with Docker, you can check out the official tutorial.
## I want to set a lot of these things, what's the best way?
One way to specify environmental variables is by adding them to a .env file located in your config folder.
That file would contain something like:
```env
KOMETA_CONFIG=/path/to/your-config-file.yml
KOMETA_TIMES=06:00,18:00
KOMETA_TRACE=true
KOMETA_LOG_REQUESTS=true
KOMETA_TIMEOUT=360
KOMETA_NO_VERIFY_SSL=true
KOMETA_COLLECTIONS_ONLY=true
```
Kometa will load those environment variables when it starts up, and you don't have to remember to set them every time you run Kometa.
???+ warning "Combining Commands or Variables"
@ -46,10 +114,11 @@ different ways to specify these things.
docker run -it -v "X:\Media\Kometa\config:/config:rw" kometateam/kometa --collections-only --run
```
## All Available Runtime Flags/Environment Variables
<divid="config"/>Specify the location of the configuration YAML file. Will default to `config/config.yml` when not
specified.
<divid="config"/>Kometa looks for its config file at `config/config.yml`. If you want to change that, perhaps to use a special-purpose `config.yml` or the like, you can use this flag to specify the location of the configuration YAML file.
<hrstyle="margin: 0px;">
@ -71,8 +140,7 @@ different ways to specify these things.
??? blank "Time to Run `-t`/`--times` `KOMETA_TIMES`<aclass="headerlink"href="#times"title="Permanent link">¶</a>"
<divid="times"/>Specify the time of day that Kometa will run. Will default to `05:00` when not
specified.
<divid="times"/>Kometa wakes up at 5:00 AM to process the config file. If you want to change that time, or tell Kometa to wake up at multiple times, use this flag.
<hrstyle="margin: 0px;">
@ -94,7 +162,7 @@ different ways to specify these things.
<divid="log-requests"/>Run with every network request printed to the Logs. **This can potentially have personal
information in it.**
<divid="log-requests"/>If you enable this, every external network request made by Kometa will be logged, along with the data that is returned. This will add a lot of data to the logs, and will probably contain things like tokens, since the auto-redaction of such things is not generalized enough to catch any token that may be in any URL.
**This can potentially have personal information in it.**
<hrstyle="margin: 0px;">
@ -357,8 +425,7 @@ different ways to specify these things.
<divid="ignore-ghost"/>Ignore all ghost logging for the run. A ghost log is what's printed to the console to show
progress during steps.
<divid="ignore-ghost"/>Kometa prints some things to the log that don't actually go into the log file on disk. Typically these are things like status messages while loading and/or filtering. If you want to hide all ghost logging for the run, use this flag.
<hrstyle="margin: 0px;">
@ -472,7 +538,7 @@ different ways to specify these things.
<divid="resume"/>Perform a resume run immediately resuming from the first instance of the specified collection,
<divid="resume"/>Perform an [immediate run](#run) starting from the first instance of the specified collection,
bypassing the time to run flag.
<hrstyle="margin: 0px;">
@ -549,7 +615,7 @@ different ways to specify these things.
??? blank "No Countdown `-nc`/`--no-countdown` `KOMETA_NO_COUNTDOWN`<aclass="headerlink"href="#no-countdown"title="Permanent link">¶</a>"
<divid="no-countdown"/>Run without displaying a countdown to the next scheduled run.
<divid="no-countdown"/>Typically, when **not** doing an [immediate run](#run), Kometa displays a countdown in the terminal where it's running. If you want to hide this countdown, use this flag.
<hrstyle="margin: 0px;">
@ -569,7 +635,7 @@ different ways to specify these things.
??? blank "No Missing `-nm`/`--no-missing` `KOMETA_NO_MISSING`<aclass="headerlink"href="#no-missing"title="Permanent link">¶</a>"
<divid="no-missing"/>Run without utilizing the missing movie/show functions.
<divid="no-missing"/>Kometa can take various actions on missing items, such as sending them to Radarr, listing them in the log, or saving a report. If you want to disable all of these actions, use this flag.
<hrstyle="margin: 0px;">
@ -589,7 +655,7 @@ different ways to specify these things.
??? blank "No Report `-nr`/`--no-report` `KOMETA_NO_REPORT`<aclass="headerlink"href="#no-report"title="Permanent link">¶</a>"
<divid="no-report"/>Run without saving the report.
<divid="no-report"/>Kometa can produce a report of missing items, collections, and other information. If you have this report enabled but want to disable it for a specific run, use this flag.
<hrstyle="margin: 0px;">
@ -609,7 +675,7 @@ different ways to specify these things.
??? blank "Read Only Config `-ro`/`--read-only-config` `KOMETA_READ_ONLY_CONFIG`<aclass="headerlink"href="#read-only-config"title="Permanent link">¶</a>"
<divid="read-only-config"/>Run without writing to the configuration file.
<divid="read-only-config"/>Kometa reads in and then writes out a properly formatted version of your `config.yml` on each run; this makes the formatting consistent and ensures that you have visibility into new settings that get added. If you want to disable this behavior and tell Kometa to leave your `config.yml` as-is, use this flag.
<hrstyle="margin: 0px;">
@ -629,7 +695,7 @@ different ways to specify these things.
<divid="divider"/>Change the terminal output divider character. Will default to `=` if not specified.
<divid="divider"/>The log is split into sections with lines of `=`. If you wish to change that character to a different one, you can do that with this flag.
<hrstyle="margin: 0px;">
@ -651,7 +717,7 @@ different ways to specify these things.
<divid="width"/>Change the terminal output width. Will default to `100` if not specified.
<divid="width"/>The log is formatted to fit within a certain width. If you wish to change that width, you can do that with this flag. Not that long lines are not wrapped or truncated to this width; this controls the minimum width of the log.
<hrstyle="margin: 0px;">
@ -677,7 +743,7 @@ different ways to specify these things.
format `KOMETA_***`, where `***` is the name you want to call the variable, will be loaded in as Config Secrets.
These Config Secrets can be loaded into the config by placing `<<***>>` in any field in the config, where `***` is
whatever name you called the variable.
whatever name you called the variable.
<hrstyle="margin: 0px;">
@ -701,3 +767,5 @@ different ways to specify these things.
tmdb:
apikey: <<mysecret>>
```
**IMPORTANT: DO NOT use underscores in the secret name. `<<mysecret>>` works, `<<my_secret>>` will not.**
Chaz Larson
1 day ago
committed by
GitHub