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):

Steps

0. Prerequisites
1. Installing Docker
2. Choosing an Installation Directory
3. Identifying Your Media Directories
4. Choosing the Right Container
5. Creating the Docker Container
6. Creating the Global Preferences File
7. Creating the Series YAML File
8. Creating Data Files
9. Adding Source Images
10. Running the Maker
11. Running the Maker on a Schedule
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 formatted as (Notice the preceding $):

$ 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:

Other Text

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.

Linux

MacOS

Windows

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.

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.

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 step.

Step 4. Choosing the Right Container

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

Docker Tag	Description	Note
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.

Step 5. Creating the Docker Container

After you've selected a tag, your installation directory, and any media directories, we're ready to create the container.

Linux and MacOS

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

$ docker run -dit \
-v "FULL_INSTALL_DIRECTORY":"FULL_INSTALL_DIRECTORY" \
-v "MEDIA_DIRECTORY":"MEDIA_DIRECTORY" \
--name TitleCardMaker \
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 "DIR":"DIR") as the other mounts.

In my example, this command looks like:

$ docker run -dit \
-v "/Documents/TitleCardMaker/":"/Documents/TitleCardMaker/" \
-v "/Documents/Media/":"/Documents/Media/" \
--name TitleCardMaker \
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 ^
-v "FULL_INSTALL_DIRECTORY":"FULL_INSTALL_DIRECTORY" ^
-v "MEDIA_DIRECTORY":"MEDIA_DIRECTORY" ^
--name TitleCardMaker ^
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 "DIR":"DIR") as the other mounts.

In my example, this command looks like:

$ docker run -dit \
-v "C:\Documents\TitleCardMaker\":"C:\Documents\TitleCardMaker\" ^
-v "C:\Documents\Media\":"C:\Documents\Media\" ^
--name TitleCardMaker ^
collinheist/titlecardmaker:master

Step 6. Creating the Global Preferences File

Starting Point

Copy the below text and save it as preferences.yml in your chosen installation folder.

options:
  source: FULL_INSTALL_DIRECTORY/source/
  series: FULL_INSTALL_DIRECTORY/tv.yml
  card_type: standard

archive:
  path: FULL_INSTALL_DIRECTORY/archives/
  
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

Paths

Replace FULL_INSTALL_DIRECTORY with your actual TitleCardMaker installation directory (see Step 2) in both options and archive.

Plex Settings

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 need to manually create your own datafiles, which is covered in Step 10.

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.

NOTE: The provided Sonarr URL should be the API v3 type of URL, so if you access Sonarr at http://192.168.0.1:8989, then you should provide http://192.168.0.1:8989/api/v3/ as the URL

TMDb

Adding an API key for TMDb allows the Maker to automatically download source images for title cards, logos for summaries, 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, which is covered in Step 11.

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 7. Creating the Series YAML File

Starting Point

Copy the below text and save it as tv.yml in the TitleCardMaker folder.

libraries:
  TV:
    path: YOUR_MEDIA_DIRECTORY/TV/

  Anime:
    path: YOUR_MEDIA_DIRECTORY/Anime/
    card_type: anime

series:
  Mr. Robot:
    year: 2015
    library: TV
    font:
      color: "#CE3F39"
      file: YOUR_INSTALL_DIRECTORY/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:
    year: 2019
    library: Anime
    translation:
      language: ja
      key: kanji
    seasons:
      1: Finding my Life's Purpose
      2: Mugen Train
      3: Entertainment District

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

Replace YOUR_INSTALL_DIRECTORY and MEDIA_DIRECTORY with the complete paths from Step 2 and 3.

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.

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

Step 8. Creating Data Files

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 9. 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 10. Running the Maker

With all the required files created, the only thing left is to run the Maker! Execute the following command to run the Maker within your Docker container:

$ docker exec -it TitleCardMaker pipenv run python main.py --run

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 9. 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.

NOTE: If you get an error when executing pipenv commands, try prefacing the command with python3 -m pipenv ...

Step 11. Running the Maker on a Schedule

The above command will run the Maker once and then stop. If you'd like to configure the Maker to automatically run on a set interval (starting at a set time), you can use the following command:

$ docker exec -it TitleCardMaker pipenv run python main.py --runtime 22:00 --frequency 12h

This runs the Maker every 12 hours, starting at 22:00 (10:00 PM local time). These can be adjusted, see here for details.

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!