All the examples in the wiki are assuming the use of this image, and many do not work with non-official Docker images due to differences in how the authors have chosen to construct their images.
One alternate image we see a lot is the Linuxserver image, due to its prominent placement in unRAID and linuxserver's general reputation.
## LinuxServer
The first image offered in unRAID for Plex Meta Manager is the Linuxserver.io image [`linuxserver/plex-meta-manager`]
This image is different to the official image [meisnate12/plex-meta-manager] in a few ways that cause a variety of problems particularly for new users.
One typical error is something like:
```
Path does not exist: /run/s6/services/plex-meta-manager/config/SOMETHING
```
The result is that the stock config file and a lot of the examples found in the wiki and config repo don't work.
If you use the LSIO image you should be aware of the following.
The LSIO image:
1. requires absolute paths in the config. /config/Movies.yml, not config/Movies.yml. Because of this most of the examples in the wiki and config repo don't work as-is with lsio. Config files that work outside of docker often fail because of this with an error referring to `/run/s6/services/...`.
2. only has `latest` version, no `develop` or `nightly`. If you want to switch to `develop` or `nightly` to try a new feature, they aren't available with LSIO image.
3. doesn't support [runtime flags](../environmental.md), only ENV vars. This means that a command like:
4. doesn't do manual runs correctly; they loop over and over. That command in the previous bullet point [which uses `PMM_RUN` to run it right now] will run over and over until you manually kill the container. The same thing using the official image will run once and quit, as expected.
5. Resets ownership of entire config dir every run. In tests, the ownership of the config dir and its contents was set to 911:911 with each run.
Generally speaking, we suggest you use the official image instead of lsio.
## Others
There are 8 other images listed at dockerhub aside from the official image and linuxserver. None of them discuss how they are different beyond one noting it includes `curl`.
Unless you have some compelling reason to use one of those, you shouldn't. You should stick with the official image.
If you choose to use another image than the default, you should should be prepared for the possibility that published examples fail in various ways.
@ -8,6 +8,17 @@ This article will walk you through getting Plex-Meta-Manager [PMM] set up and ru
4. Setting up a metadata file and creating a couple sample collections
4. Setting up a metadata file and creating a couple sample collections
5. Creating a docker container that will keep running in the background
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
2. Use `docker` to retrieve the PMM Docker image
3. Create a directory for your config files and learn how to tell Docker to use it
4. Gather two things that the script requires:
1. TMDB API Key
2. Plex URL and Token
5. Then, iteratively:
1. use `docker` to run the image
2. use a text editor to modify a couple of text files until you have a working config file and a single working metadata file.
## Prerequisites.
## Prerequisites.
Anywhere you see
Anywhere you see
@ -31,10 +42,13 @@ DO NOT MAKE ANY CHANGES BELOW if you want this to just work. Don't change the d
### Installing Docker.
### 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/)
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:
Once you have Docker installed, test it at the command line with:
[type this into your terminal]
```
```
docker run --rm hello-world
docker run --rm hello-world
```
```
@ -50,9 +64,13 @@ This message shows that your installation appears to be working correctly.
---
---
The great thing about Docker is that all the setup you'd have to do to run PMM is already done inside docker image.
#### 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; the lsio image specifically has [idiosyncracies](alternative-docker.md) that will prevent this walkthrough from working. The official image *will* behave exactly as documented below. Other very possibly won't.
The great thing about Docker is that all the setup you'd have to do to run PMM is already done inside the docker image.
That means we can just jump right into running it. At the command prompt, type:
That means we can just jump right into running it. At the command prompt, type:
```
```
@ -60,11 +78,7 @@ docker run --rm meisnate12/plex-meta-manager --run
```
```
[This is going to fail with an error, don’t panic]
This is going to fail with an error. That's expected.
### Important note on that command
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; the lsio image specifically has idiosyncracies that will prevent the walkthrough from working. The official image *will* behave exactly as documented below. Other very possibly won't.
You should see something like this:
You should see something like this:
@ -93,6 +107,7 @@ PMM, inside that Docker container, can only see other things *inside the contain
Go to your home directory and create a new directory:
Go to your home directory and create a new directory:
[type this into your terminal]
```
```
cd ~
cd ~
mkdir plex-meta-manager
mkdir plex-meta-manager
@ -100,12 +115,14 @@ mkdir plex-meta-manager
cd into that directory:
cd into that directory:
[type this into your terminal]
```
```
cd ~/plex-meta-manager
cd ~/plex-meta-manager
```
```
get the full path:
get the full path:
[type this into your terminal]
```
```
pwd
pwd
```
```
@ -138,17 +155,26 @@ This will display a full path:
```
```
</details>
</details>
You'll need to add this to the docker command every time you run it:
You'll need to add this to the docker command every time you run it, like this:
```
docker run --rm -it -v "PMM_PATH_GOES_HERE:/config:rw" meisnate12/plex-meta-manager
```
as an example:
```
<details>
docker run --rm -it -v "/Users/mroche/plex-meta-manager:/config:rw" meisnate12/plex-meta-manager
<summary>Linux</summary>
```
<br/>
```
docker run --rm -it -v "/home/YOURUSERNAME/plex-meta-manager:/config:rw" meisnate12/plex-meta-manager
```
</details>
<details>
<summary>Windows</summary>
<br/>
```
docker run --rm -it -v "C:\Users\YOURUSERNAME\plex-meta-manager:/config:rw" meisnate12/plex-meta-manager
```
</details>
If you run that command now it will display a similar error to before, but without all the image loading:
If you run that command now it will display a similar error to before, but without all the image loading:
@ -203,12 +229,12 @@ First, make a copy of the template, then open the copy in an editor:
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
Get a copy of the template to edit:
Get a copy of the template to edit [type this into your terminal]:
Open it in an editor [type this into your terminal]:
```
```
nano config.yml
nano config.yml
```
```
@ -222,6 +248,7 @@ First, make a copy of the template, then open the copy in an editor:
Download the file `https://raw.githubusercontent.com/meisnate12/Plex-Meta-Manager/master/config/config.yml.template` using a web browser or whatever means and save it in this directory as `config.yml`
Download the file `https://raw.githubusercontent.com/meisnate12/Plex-Meta-Manager/master/config/config.yml.template` using a web browser or whatever means and save it in this directory as `config.yml`
[type this into your terminal]
```
```
notepad config.yml
notepad config.yml
```
```
@ -237,50 +264,54 @@ Scroll down a bit and update the three things you just collected; Plex URL, Plex
```yaml
```yaml
plex: # Can be individually specified per library as well
plex: # Can be individually specified per library as well
libraries: # Library mappings must have a colon (:) placed after them
## This file is a template remove the .template to use the file
Movies:
libraries: # This is called out once within the config.yml file
Movies: # Each library must match the Plex library name
metadata_path:
metadata_path:
- file: config/Movies.yml # You have to create this file the other is online
- file: config/Movies.yml # This is a local file on the system
- git: meisnate12/MovieCharts
- folder: config/Movies/ # This is a local directory on the system
- git: meisnate12/MovieCharts # This is a file within the GitHub Repository
TV Shows:
TV Shows:
metadata_path:
metadata_path:
- file: config/TV Shows.yml # You have to create this file the other is online
- file: config/TVShows.yml
- git: meisnate12/ShowCharts
- folder: config/TV Shows/
- git: meisnate12/ShowCharts # This points to the https://github.com/meisnate12/Plex-Meta-Manager-Configs Repository
Anime:
Anime:
metadata_path:
metadata_path:
- file: config/Anime.yml # You have to create this file the other is online
- file: config/Anime.yml
- git: meisnate12/AnimeCharts
Music:
metadata_path:
- file: config/Music.yml
```
```
You will ultimately need an entry here for each of the libraries on which you want PMM to act. Those top-level elements [Movies, TV Shows, Anime, Music] are names of libraries on your Plex server.
You will ultimately need an entry here for each of the libraries on which you want PMM to act. Those top-level elements [Movies, TV Shows, Anime] are names of libraries on your Plex server.
For now, delete the “TV Shows”, “Anime”, and "Music" sections and change the name of the “Movies” section to “Movies-NOSUCHLIBRARY":
For now, delete the “TV Shows” and “Anime” sections and change the name of the “Movies” section to something that is NOT included in your Plex. I’m using “Movies-HIDDEN":
```yaml
```yaml
libraries:
libraries:
Movies-HIDDEN: ## <<<CHANGETHISLINE
Movies-NOSUCHLIBRARY: ## <<<CHANGETHISLINE
metadata_path:
metadata_path:
- file: config/Movies.yml
- file: config/Movies.yml
- git: meisnate12/MovieCharts
- git: meisnate12/MovieCharts
```
```
This is intended to cause an error.
This is intended to cause an error, so bear with me.
#### Testing the config file
#### Testing the config file
@ -298,12 +329,13 @@ Save the file:
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
If you're using `notepad`, type alt-`s` of choose `Save` from the `File` menu.
If you're using `notepad`, type alt-`s` or choose `Save` from the `File` menu.
</details>
</details>
Then run the script again:
Then run the script again:
[type this into your terminal]
```
```
docker run --rm -it -v "PMM_PATH_GOES_HERE:/config:rw" meisnate12/plex-meta-manager --run
docker run --rm -it -v "PMM_PATH_GOES_HERE:/config:rw" meisnate12/plex-meta-manager --run
```
```
@ -323,18 +355,18 @@ I’ve removed some of the lines for space, but have left the important bits:
...
...
| Connecting to Plex Libraries...
| Connecting to Plex Libraries...
...
...
| Connecting to Movies-HIDDEN Library... |
| Connecting to Movies-NOSUCHLIBRARY Library... |
...
...
| Plex Error: Plex Library Movies-HIDDEN not found |
| Plex Error: Plex Library Movies-NOSUCHLIBRARY not found |
| Plex Error: No Plex libraries were connected to |
| Plex Error: No Plex libraries were connected to |
...
...
```
```
You can see there that PMM found its config file, was able to connect to TMDb, was able to connect to Plex, and then failed trying to read the “Movies-HIDDEN” library, which of course doesn’t exist.
You can see there that PMM 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-HIDDEN" [or whatever you used in the previous step] to reflect your Plex. Also fix the name of the config file to match the library. Then delete any lines that start with “git”. Those are all sets of collections, and we just want to create a few as examples.
Open the config file again and change "Movies-NOSUCHLIBRARY" to reflect your Plex. Then delete any lines that start with “git”. Those are all sets of collections, and we just want to create a few as examples.
My Movies library is called “Main Movies", so mine looks like this:
My Movies library is called “Main Movies", so mine looks like this:
@ -342,11 +374,9 @@ My Movies library is called “Main Movies", so mine looks like this:
PMM may start cataloging your movies at this point; you cna hit control-C to stop that if it's happening.
PMM may start cataloging your movies at this point; you cna hit control-C to stop that if it's happening.
We can see there that it connected to the Plex Library but failed to find that `Main Movies.yml` metadata file.
We can see there that it connected to the Plex Library but failed to find that `Movies.yml` metadata file.
So far so good.
So far so good.
@ -400,7 +431,7 @@ So far so good.
Now we have to set up that metadata file that PMM just complained about.
Now we have to set up that metadata file that PMM just complained about.
This metadata file contains definitions of the actions you want PMM to take. You can find lots of examples [here](https://github.com/meisnate12/Plex-Meta-Manager-Configs):
This metadata file contains definitions of the actions you want PMM to take; these can be things like creating collections or playlists, adding overlays, changing things like posters, etc. You can find lots of examples [here](https://github.com/meisnate12/Plex-Meta-Manager-Configs) and throughout the wiki.
For now we’re going to create a few collections so you can watch the process work, then you’re on your own to create whatever others you want.
For now we’re going to create a few collections so you can watch the process work, then you’re on your own to create whatever others you want.
@ -410,8 +441,9 @@ First, open the metadata file [this will create the file if it doesn't already e
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
nano "Main Movies.yml"
nano "Movies.yml"
```
```
</details>
</details>
@ -420,14 +452,13 @@ First, open the metadata file [this will create the file if it doesn't already e
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
[type this into your terminal]
```
```
notepad "Main Movies.yml"
notepad "Movies.yml"
```
```
</details>
</details>
[of course, that should be the file name you just entered in config.yml, if you changed it from the default]
In this file, add the following, exactly as it is shown here:
In this file, add the following, exactly as it is shown here:
```yaml
```yaml
@ -459,12 +490,7 @@ I chose a letterboxd list for the last one since trakt requires authentication a
This is going to create three collections. One contains movies that feature Bill Murray. One is up to 100 movies that came out in the 1980s sorted by popularity. The last are movies that appear on a list of good endings according to Vulture.
This is going to create three collections. One contains movies that feature Bill Murray. One is up to 100 movies that came out in the 1980s sorted by popularity. The last are movies that appear on a list of good endings according to Vulture.
The first one is based on a template, so if you wanted to create a collection for another actor you just have to copy and edit those two lines [the ID comes from TMDb]. All the other config details come from the template.
The first one is based on a template to illustrate that concept. If you wanted to create a collection for another actor you just have to copy and edit those two lines [the ID comes from TMDb]. All the other config details come from the template.
```yaml
Amy Adams:
template: {name: Actor, person: 9273}
```
Save the file:
Save the file:
@ -486,6 +512,7 @@ Save the file:
Then run the script again:
Then run the script again:
[type this into your terminal]
```
```
docker run --rm -it -v "PMM_PATH_GOES_HERE:/config:rw" meisnate12/plex-meta-manager --run
docker run --rm -it -v "PMM_PATH_GOES_HERE:/config:rw" meisnate12/plex-meta-manager --run
This time you should see that the metadata file gets loaded:
This time you should see that the metadata file gets loaded:
```
```
| Loading Metadata File: config/Main Movies.yml
| Loading Metadata File: config/Movies.yml
| Metadata File Loaded Successfully
| Metadata File Loaded Successfully
```
```
@ -515,21 +542,13 @@ If you download any of the missing 22 movies on the Vulture list, running PMM wo
### What comes next:
### What comes next:
Delete these three collections if you want, from both Plex and the metadata file. If you add that “git” line you removed back into the config file:
Delete these three collections if you want, from both Plex and the metadata file [`config/Movies.yml`].
```yaml
- git: meisnate12/MovieCharts
```
then run PMM again, the script will add a whole bunch of new collections [which are defined in that file] you may be interested in.
That line is a link into the github repo of examples I referred to above, so you can review what it contains there. You can also add others from that repo using this same pattern.
If you prefer to create your own, do that in the metadata file.
Edit `Movies.yml` to reflect the actions you want PMM to perform on *your* libraries.
TV Shows and other libraries work the same way. Create a `Libraries:` section in the config.yml, create a metadata file, define collections, run the script.
TV Shows and other libraries work the same way as you've seen above. Create a section under `Libraries:` in the config.yml, create a metadata file, define collections, run the script.
Investigate the rest of the wiki to learn about everything else Plex-Meta-Manager can do for you.
Investigate the rest of the wiki to learn about everything Plex-Meta-Manager can do for you.
### Running the container in the background:
### Running the container in the background:
@ -548,4 +567,4 @@ docker run -d \
That will create a container that will run in the background until you explicitly stop it, surviving reboots, and waking up every morning at 3AM to process collections.
That will create a container that will run in the background until you explicitly stop it, surviving reboots, and waking up every morning at 3AM to process collections.
There are of course other flags you can add, which are discussed elsewhere in the wiki, but this is the minimal command to create this container.
There are of course [other flags you can add](../environmental.md), but this is the minimal command to create this container.
@ -7,6 +7,18 @@ This article will walk you through getting Plex-Meta-Manager [PMM] set up and ru
3. Setting up the initial config file
3. Setting up the initial config file
4. Setting up a metadata file and creating a couple sample collections.
4. Setting up a metadata file and creating a couple sample collections.
The specific steps you will be taking:
1. Verify that Python 3.7 or better is installed and install it if not
2. Verify that the Git tools are installed and install them if not
3. Use `git` to retrieve the code
4. Install requirements [extra bits of code required for PMM]
5. Gather two things that the script requires:
1. TMDB API Key
2. Plex URL and Token
6. Then, iteratively:
1. use `python` to run the script
2. use a text editor to modify a couple of text files until you have a working config file and a single working metadata file.
## Prerequisites.
## Prerequisites.
Nearly anywhere you see
Nearly anywhere you see
@ -22,48 +34,67 @@ This walkthrough is going to be pretty pedantic. I’m assuming you’re readin
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 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.
<h4>If you are using Windows, do everything here in Powershell. You don't need to run it as an Administrator. Git, notably, installs its own command line interface. Don't use that. Do everything here in Powershell.</h4>
This walkthrough involves typing commands into a command window. On Mac OS X or Linux, you can use your standard terminal window, whether that's the builtin Terminal app or something like iTerm. On Windows, you should use PowerShell. There are other options for command windows in Windows, but if you want this to work as written, which I assume is the case since you've read this far, you should use Powershell.
<h4>On OSX or Linux, you can use any terminal or shell.</h4>
### Starting up your terminal.
### Installing Python.
Since most of this is typing commands into a terminal, you'll need to have a terminal open.
<details>
<details>
<summary>Linux</summary>
<summary>Linux</summary>
<br/>
<br/>
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.
First let's check if it's installed already:
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, so leave it open.
</details>
```
<details>
python3 --version
<summary>OS X</summary>
```
<br/>
Open the Terminal app; this window will be the place you type commands, so leave it open. THe Terminal app is in Applications -> Utilities.
If this doesn't return `3.7.[something]` or higher, you'll need to get Python 3 installed. Describing this for any arbitrary linux is out of scope here, but if you're using Ubuntu, [this](https://techviewleo.com/how-to-install-python-on-ubuntu-linux/) might be useful.
You can also use iTerm or some other terminal app if you wish. If you don't know what that is, use Terminal.
</details>
</details>
<details>
<details>
<summary>OS X</summary>
<summary>Windows</summary>
<br/>
<br/>
First let's check if it's installed already:
Use the Start menu to open PowerShell. This will be the window into which you type commands, so leave it open.
</details>
```
python3 --version
```
If this doesn't return `3.7.[something]` or higher, you'll need to get Python 3 installed.
### Installing Python.
In order to run a Python script. the first thing you'll need is a Python interpreter. THis is typically already present on Linux and Mac, but will probably have to be installed on Windows.
First let's check if it's installed already [type this into your terminal]:
```
python3 --version
```
If this doesn't return `3.7.0` or higher, you'll need to get Python 3 installed.
<details>
<summary>Linux</summary>
<br/>
Describing a python install for any arbitrary linux is out of scope here, but if you're using Ubuntu, [this](https://techviewleo.com/how-to-install-python-on-ubuntu-linux/) might be useful.
</details>
<details>
<summary>OS X</summary>
<br/>
Follow the instructions here: [Installing Python 3 on Mac OS X](https://docs.python-guide.org/starting/install3/osx/)
Follow the instructions here: [Installing Python 3 on Mac OS X](https://docs.python-guide.org/starting/install3/osx/)
</details>
</details>
<details>
<details>
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
Go to http://www.python.org/download and download the latest version of Python for Windows in 32 or 64-bit as appropriate for your system [probably 64-bit]. As this is written, that's 3.10.4.
Go to http://www.python.org/download and download the latest version of Python for Windows in 32 or 64-bit as appropriate for your system. As this is written, that's 3.10.4.
Once downloaded, run the installer. Tick “Add to path” checkbox at the bottom and click “Install Now”.
Once downloaded, run the installer. Tick “Add to path” checkbox at the bottom and click “Install Now”.
For Windows 10, you will need to enable scripts in PowerShell. Follow the instructions [here](https://windowsloop.com/enable-powershell-scripts-execution-windows-10) to do so. If you skip this step you're going to hit a hard stop in a couple steps.
For Windows 10, you will need to enable scripts in PowerShell. Follow the instructions [here](https://windowsloop.com/enable-powershell-scripts-execution-windows-10) to do so. If you skip this step you're going to hit a hard stop in a little bit.
</details>
</details>
@ -71,16 +102,19 @@ I am assuming you do not have any of these tools already installed. When writin
### Installing git
### Installing git
To copy the Plex-Meta-Manager code to your machine, we'll be using git. This may be installed on Mac or Linux, and probably isn't in Windows.
First let's check if it's installed already [type this into your terminal]:
```
git --version
```
If this doesn't return a version number, you'll need to get git installed.
<details>
<details>
<summary>Linux</summary>
<summary>Linux</summary>
<br/>
<br/>
First let's check if it's installed already:
```
git --version
```
If this doesn't return a version number, you'll need to get git installed.
The git install is discussed here: [Download for Linux and Unix](https://git-scm.com/download/linux)
The git install is discussed here: [Download for Linux and Unix](https://git-scm.com/download/linux)
@ -89,14 +123,6 @@ I am assuming you do not have any of these tools already installed. When writin
<summary>OS X</summary>
<summary>OS X</summary>
<br/>
<br/>
First let's check if it's installed already:
```
git --version
```
If this doesn't return a version number, you'll need to get git installed.
The git install is discussed here: [Git - Downloading Package](https://git-scm.com/download/mac)
The git install is discussed here: [Git - Downloading Package](https://git-scm.com/download/mac)
</details>
</details>
@ -119,13 +145,42 @@ I am assuming you do not have any of these tools already installed. When writin
### Retrieving the Plex-Meta-Manager code
### Retrieving the Plex-Meta-Manager code
Clone the repo into your home directory:
Now we're going to use `git` to make a copy of the code on your local computer.
Clone the repo into your home directory and go into that directory [type this into your terminal]:
**NOTE: The rest of this walkthrough assumes you are staying in this directory in this terminal/Powershell window.**
<details>
<summary>What did that do?</summary>
<br/>
```
cd ~
```
This changes to your home directory, which will be something like `/home/yourname` or `/Users/yourname` or `C:\Users\YourName` depending on the platform.
This uses `git` to make a copy of (`clone`) the PMM code from where it is stored on `github`.
```
cd Plex-Meta-Manager
```
This moves into the directory that was created by the `clone` command.
</details>
Later on you can move it elsewhere if you want, but for now put it there. This will ensure that everything to follow works just like it says here. Presumably you’re reading this because the other docs are unclear to you. Don’t make unilateral changes to my assumptions while doing this.
Later on you can move it elsewhere if you want, but for now put it there. This will ensure that everything to follow works just like it says here. Presumably you’re reading this because the other docs are unclear to you. Don’t make unilateral changes to my assumptions while doing this.
<details>
<details>
@ -140,24 +195,20 @@ Later on you can move it elsewhere if you want, but for now put it there. This
No need to download a new ZIP, uncompress it, etc.
No need to download a new ZIP, uncompress it, etc.
Also, if you are asked to [or want to] switch to the latest develop code, you can do so with:
Also, if you are asked to [or want to] switch to the latest develop or nightly code, you can do so with:
```
```
git checkout develop
git checkout develop
```
```
```
git checkout nightly
```
</details>
</details>
---
---
Now move into that directory:
```
cd ~/Plex-Meta-Manager
```
**NOTE: The rest of this walkthrough assumes you are staying in this directory.**
### Setting up a virtual environment
### Setting up a virtual environment
This walkthrough is going to use a "virtual environment", since that provides a simple way to keep the requirements for a given thing self-contained; think of it as a "sandbox" for this script. It also provides a clean way to recover from mistakes, and keeps the host system clean.
This walkthrough is going to use a "virtual environment", since that provides a simple way to keep the requirements for a given thing self-contained; think of it as a "sandbox" for this script. It also provides a clean way to recover from mistakes, and keeps the host system clean.
@ -165,6 +216,7 @@ This walkthrough is going to use a "virtual environment", since that provides a
<details>
<details>
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
python3 -m venv pmm-venv
python3 -m venv pmm-venv
@ -177,6 +229,7 @@ This walkthrough is going to use a "virtual environment", since that provides a
You probably need to make sure the Python 3.9-specific virtualenv support library is installed.
You probably need to make sure the Python 3.9-specific virtualenv support library is installed.
On Linux [which is the one platform where this was seen at this point]:
On Linux [which is the one platform where this was seen at this point]:
[type this into your terminal]
```
```
sudo apt-get install python3.9-venv
sudo apt-get install python3.9-venv
```
```
@ -187,6 +240,7 @@ This walkthrough is going to use a "virtual environment", since that provides a
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
[type this into your terminal]
```
```
python -m venv pmm-venv
python -m venv pmm-venv
```
```
@ -198,13 +252,34 @@ This walkthrough is going to use a "virtual environment", since that provides a
You apparently didn't check the “Add to path” checkbox above under [installing Python](#installing-python). "Repair" your Python install and check "add python to environment variables".
You apparently didn't check the “Add to path” checkbox above under [installing Python](#installing-python). "Repair" your Python install and check "add python to environment variables".
</details>
</details>
<details>
<summary>What did that do?</summary>
<br/>
```
python3 -m venv pmm-venv
```
This tells Python3 to use the `venv` module to create a virtual environment called `pmm-venv`. The only visible effect will be the creation of a `pmm-venv` directory.
</details>
That command will not produce any output if it works; it will display an error if a problem occurs. If everything is fine, you will be looking at something like this:
```
> python -m venv pmm-venv
>
```
If you aren't looking at an error, you're ready to move on.
---
---
That will create the virtual environment, and then you need to activate it:
That will create the virtual environment, and then you need to activate it:
<details>
<details>
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
source pmm-venv/bin/activate
source pmm-venv/bin/activate
```
```
@ -213,7 +288,7 @@ That will create the virtual environment, and then you need to activate it:
<details>
<details>
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
[type this into your terminal]
```
```
.\pmm-venv\Scripts\activate
.\pmm-venv\Scripts\activate
```
```
@ -228,20 +303,39 @@ That will create the virtual environment, and then you need to activate it:
```
```
You apparently skipped the "enable scripts in Powershell" step above under [installing Python](#installing-python) for Windows.
You apparently skipped the "enable scripts in Powershell" step above under [installing Python](#installing-python) for Windows.
You will need to take care of that before moving on.
You will need to take care of that before moving on. Follow the instructions [here](https://windowsloop.com/enable-powershell-scripts-execution-windows-10).
</details>
That command will not produce any output if it works; it will display an error if a problem occurs.
You may see a change in your prompt, something like this:
Note that the prompt now shows the name of the virtual environment. You may not see this; it's dependent on *your* terminal configuration, not anything to do with Python or PMM.
<details>
<summary>What did that do?</summary>
<br/>
This tells Python to make the virtual environment "active", which means to use the copy of python that is available there, install all support libraries there, etc. This keeps the PMM code and its runtime environment totally separate from your host machine's environment.
</details>
</details>
---
---
An advantage of doing this in a venv is that in the event something goes wrong, you can delete that pmm-venv directory and do the setup again.
An advantage of doing this in a venv is that in the event something goes wrong with this part of the setup, you can delete that pmm-venv directory and do the setup again.
**IMPORTANT: In the future, when you want to run the script, you will need to do this "activation" step every time. Not the venv creation, just the activation**:
**IMPORTANT: In the future, when you want to run the script, you will need to do this "activation" step every time. Not the venv creation, just the activation**:
<details>
<details>
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
source pmm-venv/bin/activate
source pmm-venv/bin/activate
```
```
@ -250,7 +344,7 @@ An advantage of doing this in a venv is that in the event something goes wrong,
<details>
<details>
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
[type this into your terminal]
```
```
.\pmm-venv\Scripts\activate
.\pmm-venv\Scripts\activate
```
```
@ -261,7 +355,7 @@ An advantage of doing this in a venv is that in the event something goes wrong,
Plex-Meta-Manager, like every other Python script, depends on support libraries that manage things like connections to Plex, or getting things from the internet, or writing files and so on.
Plex-Meta-Manager, like every other Python script, depends on support libraries that manage things like connections to Plex, or getting things from the internet, or writing files and so on.
These support libraries are called “requirements”, and they are defined in that file called `requirements.txt`. To install them, type the following command:
These support libraries are called “requirements”, and they are defined in that file called `requirements.txt`. To install them, type the following command [type this into your terminal]:
```
```
python -m pip install -r requirements.txt
python -m pip install -r requirements.txt
@ -286,13 +380,21 @@ You should consider upgrading via the '/Users/mroche/Plex-Meta-Manager/pmm-venv/
Don't worry about the WARNING about `pip version thus-and-such` if it comes up.
Don't worry about the WARNING about `pip version thus-and-such` if it comes up.
Let’s make sure it’s working so far. At the command prompt, type:
<details>
<summary>What did that do?</summary>
<br/>
This told Python to use the `pip` module to install some libraries that PMM needs.
</details>
Let’s make sure it’s working so far. [type this into your terminal]:
```
```
python plex_meta_manager.py -r
python plex_meta_manager.py -r
```
```
[This is going to fail with an error, don’t panic]
This is going to fail with an error, which you will then fix.
You should see something like this:
You should see something like this:
@ -345,7 +447,7 @@ First, make a copy of the template. This is going to create a copy of the base
<details>
<details>
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
cp config/config.yml.template config/config.yml
cp config/config.yml.template config/config.yml
```
```
@ -354,7 +456,7 @@ First, make a copy of the template. This is going to create a copy of the base
@ -367,22 +469,22 @@ Now open the copy in an editor:
<details>
<details>
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
nano config/config.yml
nano config/config.yml
```
```
I’m using `nano` here simply because it’s built into OSX. On Linux you may need to install `nano`, or you can use any other text editor you wish provided it saves files as PLAIN TEXT.
I’m using `nano` here simply because it’s built into OSX. On Linux you may need to install `nano`, or you can use any other text editor you wish, provided it saves files as PLAIN TEXT.
</details>
</details>
<details>
<details>
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
[type this into your terminal]
```
```
notepad .\config\config.yml
notepad .\config\config.yml
```
```
I’m using `notepad` here simply because it’s built into Windows. You can use any other text editor provided it saves files as PLAIN TEXT.
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.
</details>
</details>
@ -394,55 +496,60 @@ Scroll down a bit and update the three things you just collected; Plex URL, Plex
```yaml
```yaml
plex: # Can be individually specified per library as well
plex: # Can be individually specified per library as well
libraries: # Library mappings must have a colon (:) placed after them
## This file is a template remove the .template to use the file
Movies:
libraries: # This is called out once within the config.yml file
Movies: # Each library must match the Plex library name
metadata_path:
metadata_path:
- file: config/Movies.yml # You have to create this file the other is online
- file: config/Movies.yml # This is a local file on the system
- git: meisnate12/MovieCharts
- folder: config/Movies/ # This is a local directory on the system
- git: meisnate12/MovieCharts # This is a file within the GitHub Repository
TV Shows:
TV Shows:
metadata_path:
metadata_path:
- file: config/TV Shows.yml # You have to create this file the other is online
- file: config/TVShows.yml
- git: meisnate12/ShowCharts
- folder: config/TV Shows/
- git: meisnate12/ShowCharts # This points to the https://github.com/meisnate12/Plex-Meta-Manager-Configs Repository
Anime:
Anime:
metadata_path:
metadata_path:
- file: config/Anime.yml # You have to create this file the other is online
- file: config/Anime.yml
- git: meisnate12/AnimeCharts
Music:
metadata_path:
- file: config/Music.yml
```
```
You will ultimately need an entry here for each of the libraries on which you want PMM to act. Those top-level elements [Movies, TV Shows, Anime, Music] are names of libraries on your Plex server.
You will ultimately need an entry here for each of the libraries on which you want PMM to act. Those top-level elements [Movies, TV Shows, Anime] are names of libraries on your Plex server.
For now, delete the “TV Shows”, “Anime”, and "Music" sections and change the name of the “Movies” section to “Movies-NOSUCHLIBRARY":
For now, delete the “TV Shows” and “Anime” sections and change the name of the “Movies” section to something that is NOT included in your Plex. I’m using “Movies-HIDDEN":
```yaml
```yaml
libraries:
libraries:
Movies-HIDDEN: ## <<<CHANGETHISLINE
Movies-NOSUCHLIBRARY: ## <<<CHANGETHISLINE
metadata_path:
metadata_path:
- file: config/Movies.yml
- file: config/Movies.yml
- git: meisnate12/MovieCharts
- git: meisnate12/MovieCharts
```
```
This is intended to cause an error for illustration that you will then fix.
This is intended to cause an error, so bear with me.
#### Testing the config file
#### Testing the config file
Save the file [in nano that would be cntl-x, y, return], then run the script again:
Save the file [in nano that would be cntl-x, y, return], then run the script again:
[type this into your terminal]
```shell
```shell
python plex_meta_manager.py -r
python plex_meta_manager.py -r
```
```
@ -462,15 +569,15 @@ I’ve removed some of the lines for space, but have left the important bits:
...
...
| Connecting to Plex Libraries...
| Connecting to Plex Libraries...
...
...
| Connecting to Movies-HIDDEN Library...
| Connecting to Movies-NOSUCHLIBRARY Library...
| Plex Error: Plex Library Movies-HIDDEN not found
| Plex Error: Plex Library Movies-NOSUCHLIBRARY not found
| Movies-HIDDEN Library Connection Failed
| Movies-NOSUCHLIBRARY Library Connection Failed
...
...
```
```
You can see there that PMM found its config file, was able to connect to TMDb, was able to connect to Plex, and then failed trying to read the “Movies-HIDDEN” library, which of course doesn’t exist.
You can see there that PMM 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-HIDDEN" [or whatever you used in the previous step] to reflect your Plex. Also fix the name of the metadata file to match the library. Then delete any lines that start with “git”. Those are all sets of collections, and we just want to create a few as examples.
Open the config file again and change "Movies-NOSUCHLIBRARY" to reflect *your own* Plex. Then delete any lines that start with “git”. Those are all sets of collections, and we just want to create a few as examples.
My Movies library is called “Main Movies", so mine looks like this:
My Movies library is called “Main Movies", so mine looks like this:
@ -478,29 +585,28 @@ My Movies library is called “Main Movies", so mine looks like this:
PMM may start cataloging your movies at this point; you cna hit control-C to stop that if it's happening.
PMM may start cataloging your movies at this point; you cna hit control-C to stop that if it's happening.
We can see there that it connected to the Plex Library but failed to find that `Main Movies.yml` metadata file.
We can see there that it connected to the Plex Library but failed to find that `Movies.yml` metadata file.
So far so good.
So far so good.
@ -518,7 +624,7 @@ So far so good.
Now we have to set up that metadata file that PMM just complained about.
Now we have to set up that metadata file that PMM just complained about.
This metadata file contains definitions of the actions you want PMM to take. You can find lots of examples [here](https://github.com/meisnate12/Plex-Meta-Manager-Configs):
This metadata file contains definitions of the actions you want PMM to take; these can be things like creating collections or playlists, adding overlays, changing things like posters, etc. You can find lots of examples [here](https://github.com/meisnate12/Plex-Meta-Manager-Configs) and throughout the wiki.
For now we’re going to create a few collections so you can watch the process work, then you’re on your own to create whatever others you want.
For now we’re going to create a few collections so you can watch the process work, then you’re on your own to create whatever others you want.
@ -527,9 +633,9 @@ First, open the metadata file [this will create the file if it doesn't already e
<details>
<details>
<summary>OS X/Linux</summary>
<summary>OS X/Linux</summary>
<br/>
<br/>
[type this into your terminal]
```
```
nano "config\Main Movies.yml"
nano "config\Movies.yml"
```
```
</details>
</details>
@ -537,15 +643,13 @@ First, open the metadata file [this will create the file if it doesn't already e
<details>
<details>
<summary>Windows</summary>
<summary>Windows</summary>
<br/>
<br/>
[type this into your terminal]
```
```
notepad "config\Main Movies.yml"
notepad "config\Movies.yml"
```
```
</details>
</details>
[of course, that should be the file name you just entered in config.yml, if you changed it from the default]
In this file, add the following, exactly as it is shown here:
In this file, add the following, exactly as it is shown here:
```yaml
```yaml
@ -577,15 +681,11 @@ I chose a letterboxd list for the last one since trakt requires authentication a
This is going to create three collections. One contains movies that feature Bill Murray. One is up to 100 movies that came out in the 1980s sorted by popularity. The last are movies that appear on a list of good endings according to Vulture.
This is going to create three collections. One contains movies that feature Bill Murray. One is up to 100 movies that came out in the 1980s sorted by popularity. The last are movies that appear on a list of good endings according to Vulture.
The first one is based on a template, so if you wanted to create a collection for another actor you just have to copy and edit those two lines [the ID comes from TMDb]. All the other config details come from the template.
The first one is based on a template to illustrate that concept. If you wanted to create a collection for another actor you just have to copy and edit those two lines [the ID comes from TMDb]. All the other config details come from the template.
```yaml
Amy Adams:
template: {name: Actor, person: 9273}
```
Save the file and run the script again.
Save the file and run the script again.
[type this into your terminal]
```
```
python plex_meta_manager.py -r
python plex_meta_manager.py -r
```
```
@ -597,11 +697,11 @@ This time you should see that the metadata file gets loaded:
| Metadata File Loaded Successfully
| Metadata File Loaded Successfully
```
```
And this time it will catalog all your movies. This could take a while depending on how many movies are in that library.
And this time it will catalog all your movies. This could take a while depending on how many movies are in that library. Don't cancel it this time.
Once this cataloging is complete it will move on to build those three collections.
Once this cataloging is complete it will move on to build those three collections.
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.
As it builds the collections, you should see a fair amount of logging showing which movies are being added to each collection and which ones aren’t found. Once it completes, go to Plex, go to your Movies library, and click “Collections” at the top.
@ -613,57 +713,61 @@ If you download any of the missing 22 movies on the Vulture list, running PMM wo
What comes next:
What comes next:
Delete these three collections if you want, from both Plex and the metadata file. If you add that “git” line you removed back into the config file:
Delete these three collections if you want, from both Plex and the metadata file [`config/Movies.yml`].
```yaml
- git: meisnate12/MovieCharts
```
then run PMM again, the script will add a whole bunch of new collections [which are defined in that file] you may be interested in.
Edit `Movies.yml` to reflect the actions you want PMM to perform on *your* libraries.
That line is a link into the github repo of examples I referred to above, so you can review what it contains there. You can also add others from that repo using this same pattern.
TV Shows and other libraries work the same way as you've seen above. Create a section under `Libraries:` in the config.yml, create a metadata file, define collections, run the script.
If you prefer to create your own, do that in the metadata file.
Investigate the rest of the wiki to learn about everything Plex-Meta-Manager can do for you.
TV Shows and other libraries work the same way. Create a section under `Libraries:` in the config.yml, create a metadata file, define collections, run the script.
Investigate the rest of the wiki to learn about everything else Plex-Meta-Manager can do for you.
When you are done, deactivate the virtual environment:
When you are done, deactivate the virtual environment:
[type this into your terminal]
```
```
deactivate
deactivate
```
```
## Advanced Topics
## Other Topics
### I want to use this in a context where I can't be manually activating/deactivating the virtual environment [scheduled. etc]
### I want to update to the latest version of PMM
All you need do is point to the python executable inside the virtual env. In our example, that means that if your scheduled job normally would be:
@ -5,7 +5,7 @@ To install a container from docker hub, you will need community applications - a
## Basic Installation
## Basic Installation
1. Head to the `Apps` tab of unRAID (Community Applications), and search `plex-meta-manager` in the upper right search box. No results will show, because plex-meta-manager has not been added to community applications yet. No need to fear, however, because the pre-built docker container is on docker hub. Click `Click Here To Get More Results From DockerHub`.
1. Head to the `Apps` tab of unRAID (Community Applications), and search `plex-meta-manager` in the upper right search box. There will be a couple of results shown, but you should ignore them ([Why?](alternative-docker.md)) and use the official image, which is on DockerHub. Click `Click Here To Get More Results From DockerHub`.
2. Click the download icon on the `plex meta manager` container by `meisnate12`.
2. Click the download icon on the `plex meta manager` container by `meisnate12`.
Generally, Plex-Meta-Manmager can be installed in one of two ways:
1. Running on a system as a Python script [we will refer to this as a "local" install]
2. Running as a Docker container
GENERALLY SPEAKING, running as a Docker container is simpler, as you won't have to be concerned about installing Python, or support libraries, or any possible system conflicts generated by those actions.
For this reason, it's generally recommended that you install via Docker rather than directly on the host.
If you have some specific reason to avoid Docker, or you prefer running it as a Python script for some particular reason, then this general recommendation is not aimed at you. It's aimed at someone who doesn't have an existing compelling reason to choose one over the other.
## Install Walkthroughs
## Install Walkthroughs
These installation overviews are aimed at users who have previous experience of installing services via command-line terminal commands. For those who need full installation walkthroughs, please refer to the following walkthrough guides:
The installation overviews on this page are aimed at users who have previous experience of installing services via command-line terminal commands.
For those who need full installation walkthroughs, please refer to the following walkthrough guides:
* [Local Walkthrough](guides/local)
* [Local Walkthrough](guides/local)
* [Docker Walkthrough](guides/docker)
* [Docker Walkthrough](guides/docker)
If you are using unRAID, a basic guide to container setup can be found here [this doesn't cover the PMM setup specifics found in the guides above]:
* [unRAID Walkthrough](guides/unraid)
* [unRAID Walkthrough](guides/unraid)
If you want to set PMM up under Kubernetes, see this article. As with the unRAID guide, this covers *only* the Kubernetes portion of the setup.
* [Kubernetes Walkthrough](guides/kubernetes)
* [Kubernetes Walkthrough](guides/kubernetes)
## Local Install Overview
## Local Install Overview
Plex Meta Manager is compatible with Python 3.7, 3.8 or 3.9 only. Later versions may function but are untested.
Plex Meta Manager is compatible with Python 3.7 through 3.10. Later versions may function but are untested.
These are high-level steps which assume the user has knowledge of python and pip, and the general ability to troubleshoot issues. For a detailed step-by-step walkthrough, refer to the [Local Walkthrough](guides/local) guide.
These are high-level steps which assume the user has knowledge of python and pip, and the general ability to troubleshoot issues. For a detailed step-by-step walkthrough, refer to the [Local Walkthrough](guides/local) guide.
Chaz Larson
3 years ago
committed by
meisnate12