Getting Started

Accessing the Code

Sponsors of the project will be invited to a private GitHub repository. These steps will walk you through getting the code from that repository.

After being invited, you will recieve an email at your GitHub's associated email address, open it and accept the invitation while signed into your GitHub account.

Installation

There are three primary ways to install TitleCardMaker - Docker, Docker Compose, and non-Docker. Docker Compose is generally recommended because it comes with all the requirements (Python, ImageMagick, etc.), and does not require copying any long commands.

Unraid users can directly add the container as a "template" within the UI.

Docker Compose Docker Non-Docker Unraid

Open a terminal¹ of your choice, and go to your desired install location.

Example

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

cd "~/Your/Install/Directory/TitleCardMaker"

cd "~/Your/Install/Directory/TitleCardMaker"

cd 'C:\Your\Install\Directory\TitleCardMaker'

cd 'C:\Your\Install\Directory\TitleCardMaker'

Follow these instructions to get a classic personal access token (PAT). Check the read:packages checkbox in the third section from the top.

Why is this necessary?

Because the repository is private, accessing the Docker container requires authentication.

Security Warning

Keep this access code private, as it can be used to access your GitHub account.
Store these login credentials in Docker with the following command. Type your GitHub username, and enter the PAT from Step 2 as the password.
```
docker login ghcr.io
```
Use a Docker Manager like Portainer, or Watchtower?

Some non-standard Docker managers require a different way of authenticating with private registries.

See here for Portainer, and here for Watchtower. You will need to follow the instructions specific to your system.
Determine your timezone, a full list is available here. You will want to take note of the text in the TZ Identifer column - e.g. America/Los_Angeles - for the next step.

Write the following contents to a file named docker-compose.yml in your desired install directory (from Step 1):

docker-compose.yml

name: titlecardmaker
services:
  tcm:
    image: "ghcr.io/titlecardmaker/titlecardmaker-webui:latest"
    container_name: titlecardmaker
    restart: unless-stopped
    network_mode: bridge
    ports:
      - 4242:4242
    environment:
      - TZ=America/Los_Angeles # (1)!
    # (3)
    volumes:
      - ~/Your/Install/Directory/TitleCardMaker/config:/config # (2)!

Replace this with your timezone.
Replace this with your install directory.
You may also add add PGID, PUID, and UMASK here as environment variables if you want to control the permissions of TCM.

Create (and launch) the Docker container by executing the following command.
```
docker compose up -d
```
Permission Denied?

If you get an error saying any variation of permission denied - then you should check the PAT you genered in Step 2 has read:packages permission; and that you typed docker login ghcr.io exactly.
Verify your volumes are mapped correctly by looking for a db.sqlite file inside the config directory. If you do not see one, then correct the volumes specified in Step 5 (double check your quotes are in the correct position).

Open a terminal¹ of your choice, and go to your desired install location.

Example

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

cd "~/Your/Install/Directory/TitleCardMaker"

cd "~/Your/Install/Directory/TitleCardMaker"

cd 'C:\Your\Install\Directory\TitleCardMaker'

cd 'C:\Your\Install\Directory\TitleCardMaker'

Follow these instructions to get a classic personal access token (PAT). Check the read:packages checkbox in the third section from the top.

Why is this necessary?

Because the repository is private, accessing the Docker container requires authentication.

Security Warning

Keep this access code private, as it can be used to access your GitHub account.
Store these login credentials in Docker with the following command. Type your GitHub username, and enter the PAT from Step 2 as the password.
```
docker login ghcr.io
```
Use a Docker Manager like Portainer, or Watchtower?

Some non-standard Docker managers require a different way of authenticating with private registries.

See here for Portainer, and here for Watchtower. You will need to follow the instructions specific to your system.
Determine your timezone, a full list is available here. You will want to take note of the text in the TZ Identifer column - e.g. America/Los_Angeles - for the next step.

Create (and launch) the Docker container by executing the following command - make sure to replace the install directory and timezone with your directory (from Step 2) and timezone (from Step 6).

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

docker run -itd --net="bridge" -v "~/Your/Install/Directory/TitleCardMaker/config/":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker-webui:latest"

docker run -itd --net="bridge" -v "~/Your/Install/Directory/TitleCardMaker/config/":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker-webui:latest"

docker run -itd --net="bridge" -v "C:/Your/Install/Directory/TitleCardMaker/config":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker-webui:latest"

docker run -itd --net="bridge" -v "C:/Your/Install/Directory/TitleCardMaker/config":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker-webui:latest"

User ID, Group ID, and UMASK

If you want to set the user and group which TCM is running under, then you may define the PUID, PGID, and UMASK environment variables as needed.

Permission Denied?

If you get an error saying any variation of permission denied - then you should check the PAT you genered in Step 2 has read:packages permission; and that you typed docker login ghcr.io exactly.

Verify your volumes are mapped correctly by looking for a db.sqlite file inside the config directory. If you do not see one, then correct the volumes specified in Step 5 (double check your quotes are in the correct position).

Downloading ImageMagick

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

Depending on your Linux distro, you might be able to use whatever package manager comes installed. Some of the common installations are detailed here. For example, the following command works on Debian and Ubuntu:

sudo apt-get install imagemagick

If this is not available, then you must use Docker.

Follow the ImageMagick installation and setup instructions listed here.

Download the Windows Binary Release from the ImageMagick website.

During the installation, be sure to check the Add application directory to your system path and Install legacy utilities (e.g. convert) boxes. The other options are optional.

Download the Windows Binary Release from the ImageMagick website.

During the installation, be sure to check the Add application directory to your system path and Install legacy utilities (e.g. convert) boxes. The other options are optional.

Downloading the Code

Open a terminal¹ of your choice, and go to your desired install location.

Example

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

cd "~/Your/Install/Directory/"

cd "~/Your/Install/Directory/"

cd 'C:\Your\Install\Directory\'

cd 'C:\Your\Install\Directory\'

Follow these instructions to get a classic personal access token (PAT) so that you can retrieve the TCM code from git. Check the repo scope section. Copy this code.

Why is this necessary?

Because the repository is private, the git clone command requires authentication. You can download the zipped code from the website, but this makes getting updates difficult.

A PAT is required instead of a password because GitHub does not allow passwords to be used from the command line.

Security Warning

Keep this access code private, as it can be used to access your GitHub account.

In your install directory from Step 1, clone the repository with:

git clone https://github.com/TitleCardMaker/TitleCardMaker-WebUI.git

Enter your account Username and the PAT from Step 2. The TCM code will now be downloaded into a subdirectory named TitleCardMaker-WebUI.

Running TitleCardMaker

Enter the TCM installation directory that was just created.

Example

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

cd "~/Your/Install/Directory/TitleCardMaker-WebUI"

cd "~/Your/Install/Directory/TitleCardMaker-WebUI"

cd 'C:\Your\Install\Directory\TitleCardMaker-WebUI'

cd 'C:\Your\Install\Directory\TitleCardMaker-WebUI'

Create a subfolder named config.
```
mkdir config
```

Run the following commands to install the required Python packages and launch the TCM interface.

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

python3 -m pip install uv

python3 -m uv run uvicorn app-main:app --host "0.0.0.0" --port 4242

python3 -m pip install uv

python3 -m uv run uvicorn app-main:app --host "0.0.0.0" --port 4242

python3 -m pip install uv

python3 -m uv run uvicorn app-main:app --host "0.0.0.0" --port 4242

python3 -m pip install uv

python3 -m uv run uvicorn app-main:app --host "0.0.0.0" --port 4242

You should see an output like this:

INFO:     Started server process [17385]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:4242 (Press CTRL+C to quit)

Interface not accessible?

If your log shows

INFO:     Application startup complete.

And neither the http://0.0.0.0:4242, http://localhost:4242, or your local IP address URL load into the TCM UI, then replace the 0.0.0.0 part of the previous command with your local IP address - e.g. 192.168.0.10. If you still have issues, reach out on the Discord.

Follow steps 1-4 of the Docker instructions.
At the bottom of the Docker tab of the Unraid interface, click Add Container.
Make sure Advanced View is toggled in the top-right corner.

Enter the following information - leaving all other options blank or default.

Option	Value
Name	`TitleCardMaker`
Repository	`ghcr.io/titlecardmaker/titlecardmaker-webui:latest`
Icon URL	`https://raw.githubusercontent.com/CollinHeist/TitleCardMaker/web-ui/.github/logo.png`
WebUI	`http://[IP]:[PORT:4242]/`

At the bottom of the page, click Add another Path, Port, Variable, Label or Device and enter each of the following (hitting Add after each one):

Option Value

Config Type Path

Name Config

Container Path /config

Host Path The directory from Step 1 of the Docker instructions

Option Value

Config Type Port

Name UI

Container Port 4242

Host Port 4242

Option Value

Config Type Variable

Name Timezone

Key TZ

Value The timezone from Step 1 of the Docker instructions
Hit Apply.

Success

TitleCardMaker is now accessible at the http://0.0.0.0:4242 or http://localhost:4242/ URL. It may also be at your LAN IP.

The Tutorial

The following pages of the tutorial are designed to walk you through all of the basics of using TitleCardMaker. It covers each step between installing TCM up through creating example Title Cards.

It is designed for completely new users of TCM, but is still helpful for those migrating from TCM v1.0 (the command line tool). For more detailed information about specific aspects of TitleCardMaker, look at the User Guide (after you finish the tutorial!).

- For Linux, I will assume you know what a Terminal is
- For Mac users, this is Terminal and can be found via the Spotlight
- For Windows users, this is Command Prompt or PowerShell. Both can be accessed from the search menu
↩↩↩

Option	Value
Config Type	`Path`
Name	`Config`
Container Path	`/config`
Host Path	The directory from Step 1 of the Docker instructions

Option	Value
Config Type	`Port`
Name	`UI`
Container Port	`4242`
Host Port	`4242`

Option	Value
Config Type	`Variable`
Name	`Timezone`
Key	`TZ`
Value	The timezone from Step 1 of the Docker instructions