You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Plex-Meta-Manager/docs/kometa/install/docker.md

469 lines
14 KiB

# Docker Walkthrough
7 months ago
This article will walk you through getting Kometa set up and running via Docker. It will cover:
1. Installing Docker
2. Retrieving the image
3. Setting up the initial config file
4. Setting up a collection file and creating a couple sample collections
5. Creating a docker container that will keep running in the background
The specific steps you will be taking:
1. Verify that Docker is installed and install it if not
7 months ago
2. Use `docker` to retrieve the Kometa Docker image
3. Create a directory for your config files and learn how to tell Docker to use it
7 months ago
4. Gather two things that Kometa requires:
- TMDb API Key
- Plex URL and Token
5. Then, iteratively:
- use `docker` to run the image
- use a text editor to modify a couple of text files until you have a working config file and a single working collection file.
Note that running a Docker container is inherently a pretty technical process. If you are unable or unwilling to learn the rudiments of using Docker, this may not be the tool for you.
7 months ago
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.
7 months ago
Finally, this walkthrough is intended to give you a basic grounding in how to get Kometa 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 Docker container before.
## Prerequisites
???+ tip
Nearly anywhere you see
``` { .shell .no-copy }
something like this
```
Thats a command youre going to type or paste into your terminal (OSX or Linux) or Powershell (Windows). In some cases it's displaying *output* from a command you've typed, but the difference should be apparent in context.
Additionally, anywhere you see this icon:
> :fontawesome-solid-circle-plus:
That's a tooltip, you can press them to get more information.
???+ warning "Important"
This walkthrough is going to be pretty pedantic. Im assuming youre reading it because you have no idea how to get a Docker container going, so Im proceeding from the assumption that you want to be walked through every little detail. Youre 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 whats happening. If I only give you the happy path walkthrough, then when you make a typo later on youll have no idea where that typo might be or why its breaking things.
I am assuming you do not have any of these tools already installed. When writing this up I started with a brand new Windows 10 install.
I'm also assuming you are doing this on a computer, not through a NAS interface or the like. You can do all this through something like the Synology NAS UI or Portainer or the like, but those aren't documented here. This uses the docker command line because it works the same on all platforms.
You may want to take an hour to get familiar with Docker fundamentals with the [official tutorial](https://www.docker.com/101-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, for example]; don't change the paths, etc.
### Prepare a small test library [optional]
{% include-markdown "./wt/wt-test-library.md" %}
### Starting up your terminal
Since most of this is typing commands into a terminal, you'll need to have a terminal open.
=== ":fontawesome-brands-linux: Linux"
If your Linux system is remote to your computer, connect to it via SSH. That SSH session is the terminal you will be using, so leave it open.
If you are running this on a desktop Linux machine, start up the Terminal application. That window will be the terminal you will type commands into throughout this walkthrough, so leave it open.
=== ":fontawesome-brands-apple: macOS"
Open the Terminal app; this window will be the place you type commands throughout this walkthrough, so leave it open. The Terminal app is in Applications -> Utilities.
You can also use iTerm or some other terminal app if you wish. If you don't know what that means, use Terminal.
=== ":fontawesome-brands-windows: Windows"
Use the Start menu to open PowerShell. This will be the window into which you type commands throughout this walkthrough, so leave it open.
### Installing Docker
To run Docker images, you need to have Docker installed. It is not typically installed on new Mac, Linux, or Windows machines.
The Docker install is discussed here: [Installing Docker](https://docs.docker.com/engine/install/)
Once you have Docker installed, test it at the command line with:
[type this into your terminal]
```
docker run --rm hello-world
```
You should see something that starts with:
``` { .shell .no-copy }
Hello from Docker!
This message shows that your installation appears to be working correctly.
...
```
If that doesn't work, stop here until you fix that. Diagnoing and repairing Docker install problems is out of the scope of this walkthrough.
---
#### Important note on Docker images
7 months ago
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 [idiosyncracies](images.md) that will prevent this walkthrough from working. The official image *will* behave exactly as documented below. Others very possibly won't.
7 months ago
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.
That means we can just jump right into running it. At the command prompt, type:
```
7 months ago
docker run --rm kometateam/kometa --run
```
This is going to fail with an error. That's expected.
You should see something like this:
``` { .shell .no-copy }
7 months ago
Unable to find image 'kometateam/kometa:latest' locally
latest: Pulling from kometateam/kometa
7d63c13d9b9b: Already exists
6ad2a11ca37b: Already exists
8076cdef4689: Pull complete
0ba90f5a7dd0: Pull complete
27c191df269f: Pull complete
c75e4c0924fa: Pull complete
ed6716577767: Pull complete
0547721ab7a3: Pull complete
ea4d35bce959: Pull complete
Digest: sha256:472be179a75259e07e68a3da365851b58c2f98383e02ac815804299da6f99824
7 months ago
Status: Downloaded newer image for kometateam/kometa:latest
Config Error: config not found at //config
```
That error means you dont have a config file, but we know that most everything is in place to run the image.
### Setting up a volume map
7 months ago
Kometa, inside that Docker container, can only see other things *inside the container*. We want to add our own files for config and metadata, so we need to set something up that lets Kometa see files we create *outside* the container. This is called a "volume map".
Go to your home directory and create a new directory:
[type this into your terminal]
``` { .shell .no-copy linenums="1"}
cd ~ #(1)!
7 months ago
mkdir kometa #(2)!
```
1. This changes to your home directory, which will be something like `/home/yourname` or `/Users/yourname` or `C:\Users\YourName` depending on the platform.
7 months ago
2. This creates a directory called "kometa"
cd into that directory and create another directory:
[type this into your terminal]
``` { .shell .no-copy linenums="1"}
7 months ago
cd ~/kometa #(1)!
mkdir config #(2)!
```
7 months ago
1. This navigates to the kometa folder within your home directory.
2. This creates a directory called "config"
3. get the full path:
[type this into your terminal]
```
pwd
```
This will display a full path:
=== ":fontawesome-brands-linux: Linux"
``` { .shell .no-copy }
7 months ago
/home/YOURUSERNAME/kometa
```
=== ":fontawesome-brands-apple: macOS"
``` { .shell .no-copy }
7 months ago
/Users/YOURUSERNAME/kometa
```
=== ":fontawesome-brands-windows: Windows"
``` { .shell .no-copy }
7 months ago
C:\Users\YOURUSERNAME\kometa
```
Add "config" onto the end of that to get the host path to your config directory, for example:
=== ":fontawesome-brands-linux: Linux"
```
7 months ago
/home/YOURUSERNAME/kometa/config
```
=== ":fontawesome-brands-apple: macOS"
```
7 months ago
/Users/YOURUSERNAME/kometa/config
```
=== ":fontawesome-brands-windows: Windows"
```
7 months ago
C:\Users\YOURUSERNAME\kometa\config
```
You'll need to add this to the docker command every time you run it, like this:
=== ":fontawesome-brands-linux: Linux"
```
7 months ago
docker run --rm -it -v "/home/YOURUSERNAME/kometa/config:/config:rw" kometateam/kometa
```
=== ":fontawesome-brands-apple: macOS"
```
7 months ago
docker run --rm -it -v "/Users/YOURUSERNAME/kometa/config:/config:rw" kometateam/kometa
```
=== ":fontawesome-brands-windows: Windows"
```
7 months ago
docker run --rm -it -v "C:\Users\YOURUSERNAME\kometa\config:/config:rw" kometateam/kometa
```
If you run that command now it will display a similar error to before, but without all the image loading:
``` { .bash .no-copy }
7 months ago
$ docker run --rm -it -v "/Users/mroche/kometa/config:/config:rw" kometateam/kometa --run
Config Error: config not found at //config
```
Note that I show the example path there.
<details>
<summary>Why did we create that `config' directory?</summary>
This was done so that from here on in the instructions match between this walkthrough and the [Local walkthrough](local.md).
</details>
### 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.
=== ":fontawesome-brands-linux: Linux"
[type this into your terminal]
```
mkdir config/assets
```
=== ":fontawesome-brands-apple: macOS"
[type this into your terminal]
```
mkdir config/assets
```
=== ":fontawesome-brands-windows: Windows"
[type this into your terminal]
```
mkdir config\assets
```
### Setting up the initial config file
{%
include-markdown "./wt/wt-01-basic-config.md"
%}
#### Editing the config template
First, make a copy of the template:
=== ":fontawesome-brands-linux: 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
```
=== ":fontawesome-brands-apple: macOS"
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
```
=== ":fontawesome-brands-windows: Windows"
Go to [this URL](https://raw.githubusercontent.com/Kometa-Team/Kometa/master/config/config.yml.template) using a web browser; choose the "Save" command, then save the file at:
```
7 months ago
C:\Users\YOURUSERNAME\kometa\config\config.yml
```
Now open the copy in an editor:
{%
include-markdown "./wt/wt-editor.md"
%}
{%
include-markdown "./wt/wt-02-config-bad-library.md"
%}
#### Testing the config file
Save the file:
{%
include-markdown "./wt/wt-save.md"
%}
7 months ago
Then run Kometa again:
{%
include-markdown "./wt/wt-run-docker.md"
%}
{%
include-markdown "./wt/wt-03-lib-err-and-fix.md"
%}
### Creating a few sample collections
{%
include-markdown "./wt/wt-04-default-intro.md"
%}
7 months ago
So let's run Kometa and see this happen:
{%
include-markdown "./wt/wt-run-docker.md"
%}
{%
include-markdown "./wt/wt-04b-default-after.md"
%}
### Setting up a collection file and creating a few sample collections
{%
include-markdown "./wt/wt-05-local-file.md"
%}
Save the file:
{%
include-markdown "./wt/wt-save.md"
%}
7 months ago
Then run Kometa again:
{%
include-markdown "./wt/wt-run-docker.md"
%}
{%
include-markdown "./wt/wt-06-local-after.md"
%}
### Adding Overlays to movies
{%
include-markdown "./wt/wt-07-overlay-add.md"
%}
Save the file:
{%
include-markdown "./wt/wt-save.md"
%}
7 months ago
Then run Kometa again:
{%
include-markdown "./wt/wt-run-docker.md"
%}
{%
include-markdown "./wt/wt-08-overlay-after.md"
%}
{%
include-markdown "./wt/wt-09-next-steps.md"
%}
## Other Topics
### Scheduling
{%
include-markdown "./wt/wt-10-scheduling.md"
%}
### I want to use the develop branch
Add the `develop` tag to the image name in your run command [or wherever you specify the image in your environment]
```
7 months ago
docker run --rm -it -v "KOMETA_PATH_GOES_HERE:/config:rw" kometateam/kometa:develop --run
^^^^^^^
```
This may not work if you are not using the official image.
### I want to use the nightly branch
Add the `nightly` tag to the image name in your run command [or wherever you specify the image in your environment]
```
7 months ago
docker run --rm -it -v "KOMETA_PATH_GOES_HERE:/config:rw" kometateam/kometa:nightly --run
^^^^^^^
```
This may not work if you are not using the official image.
### I want to ensure I am using the master branch
Add the `latest` tag to the image name in your run command [or wherever you specify the image in your environment]
```
7 months ago
docker run --rm -it -v "KOMETA_PATH_GOES_HERE:/config:rw" kometateam/kometa:latest --run
^^^^^^
```