Docker Tutorial

Introduction

The TitleCardMaker can also be installed with Docker. The benefit of using a Docker container is that all the required packages and software are already installed for you (skipping steps 1-7 of to the regular setup process).

The following steps will walk you through a fresh installation using the docker container, and creation of the following Title Cards (for demonstrative purposes):

Sample Docker Compose

Expand

---
version: "2.1"
services:
  titlecardmaker:
    image: collinheist/titlecardmaker:TAG_HERE    # master or develop
    container_name: TitleCardMaker
    environment:
      - PUID=1000                                 # Your GID/UID
      - PGID=1000
      - TZ=America/Detroit                        # your time zone
      - TCM_MISSING=/config/missing.yml
      - TCM_RUNTIME=22:00
      - TCM_FREQUENCY=12h
    volumes:
      - FULL_INSTALL_DIRECTORY\config:/config    # Change these
      - FULL_INSTALL_DIRECTORY\config:/maker/logs
    restart: unless-stopped

Steps

0. Prerequisites
1. Installing Docker
2. Choosing an Installation Directory
3. Identifying Your Media Directories
4. Choosing the Right Container
5. Creating the Global Preferences File
6. Creating the Series YAML File
7. Creating Data Files
8. Adding Source Images
9. Creating the Docker Container
10. The Results
11. Syncing with Sonarr, Plex, or Emby
12. Patting Yourself on the Back

NOTE: Sonarr is not required by the Maker, however if unused you will have to manually enter all episode titles for each show (which is very tedious). I strongly recommend you install this - but installation will not be covered here. See here, even if you're not using it to gather your media itself.

Step 0. Prerequisites

Referring to Files

Throughout this process, I will often write file or directories as /some/document (using the forward slash /). Although this is the correct way to specify filepaths on Linux and MacOS, Windows users should interpret these as their Windows counterparts - i.e. \some\document.

I also do not know your specific file layout, so a lot of the file references here are relative to the TitleCardMaker directory created in step 6. This means when I write source/some file (for example) that is within the TitleCardMaker directory, wherever you choose to install that.

Running Commands

Text that is written as..

some_command

Is a command, and is intended to be run in the terminal (sometimes called console).

For MacOS and Linux, this is the Terminal application:

And on Windows this is Powershell:

YAML

There will also be text, often referred to as YAML that will be written like (notice the highlighting and use of colons :):

stuff:
  other_stuff: 123

This is YAML, and can be written as normal text in whatever plain text editor you have (such as Notepad or TextEdit).

NOTE: When writing things text in YAML files with a colon followed by a space (: ), this must be entered in quotes. So for example: Avatar: The Last Airbender would need to be entered as "Avatar: The Last Airbender"

NOTE: It is important, when writing your own YAML and copying the YAML from this tutorial, that you use the spacing as shown. YAML files use indents to detect what information is underneath or "an attribute of" other info.

---

Step 1. Installing Docker

First check if Docker is installed:

docker version --format '{{.Server.Version}}'

If this doesn't print some version number like xx.yy.zz, you'll need to install Docker.

---

Step 2. Choosing an Installation Directory

Background

Docker containers aren't "installed" like a typical program in that you don't put a Docker container into a specific folder; instead, think of it as installing a completely separate file system on your machine.

Because the container's filesystem is separated from your machine's, you need to pass your local configuration and media files into the Docker container. This will allow the Maker to access your files. This is done by "mounting" or "mapping" (interchangeable terms) a "volume".

Selecting a Folder

Identify where you want to store all the configuration files for the Maker (such as your preferences, source files, etc.) For this example, I'll be installing the Maker at /Documents/TitleCardMaker/.

Get the complete filepath of this installation directory (such as /Documents/TitleCardMaker/ or C:\Documents\TitleCardMaker). This is the volume we'll mount into the docker container, so take note of it for Step 5.

---

Step 3. Identifying Your Media Directories

If you want the Maker to create title cards and store them alongside their associated media (i.e. video and card files in the same folders), then you will also need to mount your media directories into the Maker. This is not required or recommended, and putting all your cards in a local card folder WILL be easier.

For this example, I'll assume my media is at /Documents/Media/. Get the complete filepath of this directory. This is another volume we'll mount into the docker container, so take note of it for Step 5. This will be mounted to /Media in the container.

NOTE: If your libraries are in separate folders or drives, that's no problem. You can mount any number of volumes when creating the Docker container. Just take note of each of these directories for the following steps.

---

Step 4. Choosing the Right Container

There are two choices/tags of docker container to use, both are outlined below:

Docker Tag	Description	Note
latest	The most up-to-date (stable) release of the Maker	Recommended for most users
master	The most up-to-date (stable) release of the Maker	Recommended for most users
develop	The work-in-progress (unstable) release of the Maker	Not recommended unless you want to work with or test new features

These tags are identical to the branches you see here on GitHub (latest being the same as master).

---

Step 5. Creating the Global Preferences File

Starting Point

Copy the below text and save it at TitleCardMaker/config/preferences.yml in your chosen installation folder.

options:
  source: /config/source/
  series: /config/tv.yml
  episode_data_source: sonarr
  
plex:
  url: YOUR_PLEX_URL
  token: YOUR_PLEX_TOKEN

sonarr:
  url: YOUR_SONARR_URL
  api_key: YOUR_SONARR_API_KEY

tmdb:
  api_key: YOUR_TMDB_API_KEY

NOTE: Although not explicitly covered in this tutorial, Emby and Jellyfin can be used instead of (or alongside) Plex. The setup is practically the same, but an example of the Emby settings can be found here.

Plex

Adding your Plex configuration details allows the Maker to automatically refresh the metadata of a show after it's created title cards.

If you are not using Plex, or do not want the Maker to automatically set the title cards within Plex, delete the entire plex section. If you still want Plex to pull in the cards the "manual way" (i.e. matching filenames), you will need to configure Plex to use local assets

If you are using Plex, replace YOUR_PLEX_URL with the URL of your Plex server; and YOUR_PLEX_TOKEN with your Plex X-Token - the process to get this is detailed here.

Sonarr

Adding your Sonarr configuration details allows the Maker to automatically get episode titles, and improves the accuracy and speed of the automated image gathering process.

If you are not using Sonarr, delete the entire sonarr section. In this case, you'll also need to change the episode_data_source setting under options to either tmdb or plex (see more here).

If you are using Sonarr, replace YOUR_SONARR_URL with the URL of your Sonarr URL; and YOUR_SONARR_API_KEY with your Sonarr's API key. This API key can be accessed via Settings > General > Security > API Key (see below). For each series you want to get episodes from, you need to make sure to add it within Sonarr.

TMDb

Adding an API key for TMDb allows the Maker to automatically download source images for title cards, logos for summaries and cards, and translated episode titles.

If you are not using TMDb, delete the entire tmdb section. In this case, you'll need to find and download your own source images (or set TCM to grab them from Plex), which is covered in Step 10.

If you are using TMDb, replace YOUR_TMDB_API_KEY with your personal API key from TMDb. To get the API key, follow TMDb's instructions.

---

Step 6. Creating the Series YAML File

The following YAML is an example which showcases many of the commonly used features of TCM. After the tutorial can (and probably should be) removed or modified.

Starting Point

Copy the below text and save it at TitleCardMaker/config/tv.yml.

libraries:
  TV:
    path: /Media/TV/

  Anime:
    path: /Media/Anime/
    card_type: anime

series:
  Mr. Robot (2015):
    library: TV
    font:
      color: "#CE3F39"
      file: /config/fonts/MR ROBOT.ttf
    seasons:
      0: "specials_0.0"
      1: "season_1.0"
      2: "season_2.0"
      3: "season_3.0"
      4: "season_4.0"
  
  "Demon Slayer: Kimetsu no Yaiba (2019)":
    library: Anime
    translation:
      language: ja
      key: kanji
    seasons:
      1: Finding my Life's Purpose
      2: Mugen Train
      3: Entertainment District

  The Mandalorian (2019):
    library: TV
    card_type: star wars
    episode_text_format: "Chapter {abs_number}"

Create a folder called fonts in your TitleCardMaker installation directory, and then download the Mr. Robot font from here, and save it at fonts/MR ROBOT.ttf.

Explanation

For the example, we'll assume you have two Plex libraries called "TV" and "Anime", and that they live under the Media directory. This directory comes from step 3 (rename these to fit your server).

There is a lot of detail here. All aspects are explained in greater detail here.

---

Step 7. Creating Data Files

NOTE: If you have properly assigned your episode data source, you can skip this step as TCM will create data files for you. This is the case for 99.9% of users.

Data files are where episode data is stored for creating title cards. These are described in detail here. If you enable Sonarr, the Maker will automatically create and update these for you.

For this example, we'll be creating them manually to create the three cards shown at the beginning. Start by creating a folder called source underneath your TitleCardMaker installation directory.

Mr. Robot

Create a folder underneath source called Mr. Robot (2015). Within that folder, copy the below text and save it in a text file called data.yml:

data:
  Season 1:
    2:
      title: eps1.1_ones-and-zeroes.mpeg

Demon Slayer - Kimetsu no Yaiba

Create a folder underneath source called Demon Slayer - Kimetsu no Yaiba (2019). Within that folder, copy the below text and save it in a text file called data.yml:

data:
  Season 3:
    10:
      title: Never Give Up
      kanji: 絶対諦めない

The Mandalorian

Create a folder underneath source called The Mandalorian (2019). Within that folder, copy the below text and save it in a text file called data.yml:

data:
  Season 1:
    2:
      title: "Chapter 2: The Child"
      abs_number: 2

---

Step 8. Adding Source Images

If you've enabled TMDb, then the Maker will (attempt to) download the images for each episode automatically. For this example, download the following images manually:

• Download Mr. Robot S01E02 and save it at source/Mr. Robot (2015)/s1e2.jpg
• Download Demon Slayer - Kimetsu no Yaiba S03E10 and save it at source/Demon Slayer - Kimetsu no Yaiba (2019)/s3e10.jpg
• Download The Mandalorian S01E02 and save it at source/The Mandalorian (2019)/s1e2.jpg

---

Step 9. Creating and Running the Docker Container

After you've selected a tag, your installation directory, and any media directories, we're ready to create and run the container. The container created here will run immediately, and then every 12 hours starting at 10:00 PM (feel free to change these).

NOTE: See a more detailed list of the available docker variables here

Linux and MacOS

From the command line, execute the following (the command has been broken into multiple lines for easier reading):

docker run -dit \
--name TitleCardMaker \
-v "FULL_INSTALL_DIRECTORY/config":"/config" \
-v "FULL_INSTALL_DIRECTORY/log":"/maker/logs" \
-v "MEDIA_DIRECTORY":"/Media" \
-e TCM_MISSING="/config/missing.yml" \
-e TCM_RUNTIME="22:00" \
-e TCM_FREQUENCY="12h" \
collinheist/titlecardmaker:TAG_HERE

Replace FULL_INSTALL_DIRECTORY with the complete path from Step 2; MEDIA_DIRECTORY with the complete path from Step 3; and TAG_HERE with your chosen tag (master or develop) from Step 4. If you have and are mounting more than one Media directory, follow the same structure (-v "MEDIA_DIR":"/MediaDirName") as the other mounts.

NOTE: If you wish to use a specific group and user ID (GID/UID), then those can be passed to this command as well, like -e PGID="314" -e PUID="314"

In my example, this command looks like:

docker run -dit \
--name TitleCardMaker \
-v "/Documents/TitleCardMaker/config":"/config" \
-v "/Documents/TitleCardMaker/log":"/maker/logs" \
-v "/Documents/Media/":"/Media" \
-e TCM_MISSING="/config/missing.yml" \
-e TCM_RUNTIME="22:00" \
-e TCM_FREQUENCY="12h" \
collinheist/titlecardmaker:master

Windows

From the command line, execute the following (the command has been broken into multiple lines for easier reading):

docker run -dit `
--name TitleCardMaker `
-v "FULL_INSTALL_DIRECTORY\config":"/config" `
-v "FULL_INSTALL_DIRECTORY\log":"/maker/logs" `
-v "MEDIA_DIRECTORY":"/Media" `
-e TCM_MISSING="/config/missing.yml" `
-e TCM_RUNTIME="22:00" `
-e TCM_FREQUENCY="12h" `
collinheist/titlecardmaker:TAG_HERE

NOTE: The line-continuation character (`) is optional, and is only present for easier reading. If you are using Shell instead of PowerShell, the equivalent character is ^.

Replace FULL_INSTALL_DIRECTORY with the complete path from Step 2; MEDIA_DIRECTORY with the complete path from Step 3; and TAG_HERE with your chosen tag (master or develop) from Step 4. If you have and are mounting more than one Media directory, follow the same structure (-v "DIR":"DIR") as the other mounts.

In my example, this command looks like:

docker run -dit `
--name TitleCardMaker `
-v "C:\Documents\TitleCardMaker\config":"/config" `
-v "C:\Documents\TitleCardMaker\log":"/maker/logs" `
-v "C:\Documents\Media\":"/Media" `
-e TCM_MISSING="/config/missing.yml" `
-e TCM_RUNTIME="22:00" `
-e TCM_FREQUENCY="12h" `
collinheist/titlecardmaker:master

---

Step 10. The Results

If you've enabled Sonarr, this will modify the datafiles we just created and add all the episode info from Sonarr. However, existing episode data is not overwritten in this process.

The Maker will then systematically create title cards for each show we defined in step 7. These will be located under media/TV/Mr. Robot (2015)/Season 1/Mr. Robot (2015) - S01E02.jpg, media/Anime/Demon Slayer - Kimetsu no Yaiba (2019)/Season 3/Demon Slayer - Kimetsu no Yaiba (2019) - S03E10.jpg, and media/TV/The Mandalorian (2019)/Season 1/The Mandalorian (2019) - S01E02.jpg.

If you've enabled Sonarr, it will also create title cards for all other episodes of those series.

---

Step 11. Syncing with Sonarr, Plex, or Emby

The manual creation of series YAML files (the files that list which series to create title cards for), detailed in step 6, can be quite tedious if you have hundreds of series you want to create cards for. To make this easier, TCM can "sync" to either Sonarr, Plex, or Emby and create a generic series YAML file for you.

If you're using Sonarr, I'd personally recommend that over Plex/Emby, as their API's are relatively slow and Sonarr's tags can be utilized to create more customized behavior. Setting up this sync behavior is detailed here.

---

Step 12. Patting Yourself on the Back

Feel free to reach out on the discord if there has been any hitches along the way, or you have any questions or suggestions! And if you feel so inclined, support the project on GitHub or BuyMeACoffee!

---