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.
If the idea of editing YAML files by hand is daunting, this may not be the tool for you. All the configuration of Plex Meta Manager 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 Plex Meta Manager running. It doesn't cover how to create your own collections, or how to add overlays, or any of the myriad other things Plex Meta Manager 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
```
That’s a command you’re 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. I’m assuming you’re reading it because you have no idea how to get a Docker container going, 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.
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
This tutorial uses the official image, and you should, too. Don't change `meisnate12/plex-meta-manager` 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.
The great thing about Docker is that all the setup you'd have to do to run Plex Meta Manager is already done inside the docker image.
That means we can just jump right into running it. At the command prompt, type:
```
docker run --rm meisnate12/plex-meta-manager --run
```
This is going to fail with an error. That's expected.
You should see something like this:
``` { .shell .no-copy }
Unable to find image 'meisnate12/plex-meta-manager:latest' locally
Status: Downloaded newer image for meisnate12/plex-meta-manager:latest
Config Error: config not found at //config
```
That error means you don’t have a config file, but we know that most everything is in place to run the image.
### Setting up a volume map
Plex Meta Manager, 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 Plex Meta Manager 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)!
mkdir plex-meta-manager #(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.
2. This creates a directory called "plex-meta-manager"
cd into that directory and create another directory:
[type this into your terminal]
``` { .shell .no-copy linenums="1"}
cd ~/plex-meta-manager #(1)!
mkdir config #(2)!
```
1. This navigates to the plex-meta-manager 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 }
/home/YOURUSERNAME/plex-meta-manager
```
=== ":fontawesome-brands-apple: macOS"
``` { .shell .no-copy }
/Users/YOURUSERNAME/plex-meta-manager
```
=== ":fontawesome-brands-windows: Windows"
``` { .shell .no-copy }
C:\Users\YOURUSERNAME\plex-meta-manager
```
Add "config" onto the end of that to get the host path to your config directory, for example:
=== ":fontawesome-brands-linux: Linux"
```
/home/YOURUSERNAME/plex-meta-manager/config
```
=== ":fontawesome-brands-apple: macOS"
```
/Users/YOURUSERNAME/plex-meta-manager/config
```
=== ":fontawesome-brands-windows: Windows"
```
C:\Users\YOURUSERNAME\plex-meta-manager\config
```
You'll need to add this to the docker command every time you run it, like this:
=== ":fontawesome-brands-linux: Linux"
```
docker run --rm -it -v "/home/YOURUSERNAME/plex-meta-manager/config:/config:rw" meisnate12/plex-meta-manager
```
=== ":fontawesome-brands-apple: macOS"
```
docker run --rm -it -v "/Users/YOURUSERNAME/plex-meta-manager/config:/config:rw" meisnate12/plex-meta-manager
```
=== ":fontawesome-brands-windows: Windows"
```
docker run --rm -it -v "C:\Users\YOURUSERNAME\plex-meta-manager\config:/config:rw" meisnate12/plex-meta-manager
```
If you run that command now it will display a similar error to before, but without all the image loading:
``` { .bash .no-copy }
$ docker run --rm -it -v "/Users/mroche/plex-meta-manager/config:/config:rw" meisnate12/plex-meta-manager --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]:
Go to [this URL](https://raw.githubusercontent.com/meisnate12/Plex-Meta-Manager/master/config/config.yml.template) using a web browser; choose the "Save" command, then save the file at:
