tModLoader Powered By Docker

View on Github | View on Dockerhub

This Docker Image is designed to allow for easy configuration and setup of a modded Terraria server powered by tModLoader.

Features

• Easy Downloading of tModLoader mods by Workshop ID
• Scheduled World Saving
• Graceful Shutdowns
• Configuration Files are optional
• Github Automation to stay up-to-date with tModLoader's release cycle

Credits & Mentions

• Terraria
  • Website
  • Steam Store Page
• tModLoader
  • Website
  • Steam Store Page
  • Github
• ldericher's Docker implementation of tModLoader for Terraria 1.3 and command injection functionality
• rfvgyhn's Docker implementation of tModLoader for Terraria 1.3
• guillheu's Docker implementation of tModLoader for Terraria 1.4
• FlorentLM For helping clean up the Dockerfile & resolving some security concerns.

Check out all of my Terraria Images!

1.4 Vanilla Terraria: Github | Dockerhub

1.4 tModLoader: Github | Dockerhub

Repository Automation & Daily Automated Builds

The Github repository has been configured with an automated workflow to check for tModLoader updates daily and update the latest image and Dockerfile with the new tModLoader version.

Additionally, the Dockerhub registry will maintain all previous versions which are processed through this automated workflow. You can access these previous versions by pulling a repository with the tModLoader version string as the tag.

To Pull the Latest tModLoader Image

# ":latest" will pull the most recent tModLoader version from https://github.com/tModLoader/tModLoader/releases/latest
docker pull jacobsmile/tmodloader1.4:latest

To Pull a Specific tModLoader Image Version

# Replace 'v2022.09.47.13' with the version string found at https://github.com/tModLoader/tModLoader/releases
docker pull jacobsmile/tmodloader1.4:v2022.09.47.13

Container Preparation

Data Directory

Create a directory on HOST machine to house persistent files.

# Making the Data directory
mkdir /path/to/data/directory

# The below line is a mapped volume for the Docker container.
-v /path/to/data/directory:/data

Within this directory, you will find the following file structure:

/data/
├─ steamMods/
│  ├─ steamapps/
│  │  ├─ workshop/
│  │  │  ├─ content/
│  │  │  │  ├─ 1281930/
├─ tModLoader/
│  ├─ ModConfigs/
│  ├─ Mods/
│  │  ├─ enabled.json
│  ├─ Worlds/

Steam Workshop content is stored within steamMods.

The server's Mod Configurations, Mod directory and World directories are stored within tModLoader.

Downloading Mods

Every Workshop item on Steam has a unique identifier which can be found by visiting the store page directly. For example, for the Calamity Mod, you can find the Workshop ID from the URL. In this case, 2824688072 is the ID. This Docker container is capable of downloading tModLoader mods directly from the Steam Workshop to streamline the setup process.

In the environment variables passed to the container at runtime, specify the TMOD_AUTODOWNLOAD variable with a value of a comma separated list of the Mod IDs you wish to download.

For example, to tell the container to download Calamity and the Calamity Mod Music, specify the following variable:

-e TMOD_AUTODOWNLOAD=2824688072,2824688266

Enabling Mods

To successfully run this container, it is important to understand the difference between downloading mods and enabling mods.

Downloading a mod simply stores it in the Steam Workshop cache, which is stored in the /data/mods directory. When mapping /data to a HOST directory, this will allow for persistence between container restarts.

Enabling a mod tells the container to write the Mod's name to the enabled.json file, which tModLoader reads during startup. A Mod must first be downloaded with the TMOD_AUTODOWNLOAD variable to be eligible to be enabled.

To enable a mod on the server, specify the TMOD_ENABLEDMODS environment variabe with a value of a comma separated list of the Mod IDs you wish to enable.

-e TMOD_ENABLEDMODS=2824688072,2824688266

Mod Considerations

There is no need to repeatedly download mods each time you start the container. For this reason, once you have downloaded the mods you want to include on your server, it is safe to remove the TMOD_AUTODOWNLOAD environment variable, whilst maintaining the TMOD_ENABLEDMODS variable to enable them during runtime. Doing so will greatly improve the startup time of the Docker container.

If mods receive updates you wish to download, include the Mod ID again in the TMOD_AUTODOWNLOAD variable to download the update. The next time tModLoader starts, the mod will be updated.

Additionally, you may at any time remove a mod from the TMOD_ENABLEDMODS variable to disable it, though this may cause problems with a world which has modded content.

Environment Variables

The following are all of the environment variables that are supported by the container. These handle server functionality and Terraria server configurations.

The following are environment variables which control Journey Mode settings. For all of these settings,

• 0 = Locked for everyone
• 1 = Only Changeable by Host
• 2 = Can be changed by everyone.

Refer to the Terraria Server Wiki for more information. The default setting for all of these is 0 when not explicitly set.

• TMOD_JOURNEY_SETFROZEN
• TMOD_JOURNEY_SETDAWN
• TMOD_JOURNEY_SETNOON
• TMOD_JOURNEY_SETDUSK
• TMOD_JOURNEY_SETMIDNIGHT
• TMOD_JOURNEY_GODMODE
• TMOD_JOURNEY_WIND_STRENGTH
• TMOD_JOURNEY_RAIN_STRENGTH
• TMOD_JOURNEY_TIME_SPEED
• TMOD_JOURNEY_RAIN_FROZEN
• TMOD_JOURNEY_WIND_FROZEN
• TMOD_JOURNEY_PLACEMENT_RANGE
• TMOD_JOURNEY_SET_DIFFICULTY
• TMOD_JOURNEY_BIOME_SPREAD
• TMOD_JOURNEY_SPAWN_RATE

Running the Container

Docker Command

# Pull the image
docker pull jacobsmile/tmodloader1.4:latest

# Execute the container
docker run -p 7777:7777 --name tmodloader --rm \
  -v /path/to/data:/data
  -e TMOD_SHUTDOWN_MESSAGE='Goodbye!' \
  -e TMOD_AUTOSAVE_INTERVAL='15' \
  -e TMOD_AUTODOWNLOAD='2824688072,2824688266' \
  -e TMOD_ENABLEDMODS='2824688072,2824688266' \
  -e TMOD_MOTD='Welcome to my tModLoader Server!' \
  -e TMOD_PASS='secret' \
  -e TMOD_MAXPLAYERS='16' \
  -e TMOD_WORLDNAME='Earth' \
  -e TMOD_WORLDSIZE='2' \
  -e TMOD_WORLDSEED='not the bees!' \
  -e TMOD_DIFFICULTY='3' \
  jacobsmile/tmodloader1.4

Docker Compose

Included in the Github repository is a sample docker-compose.yml file. Refer to the contents of this file to learn how to configure this file.

Once you are satisfied with the compose file, start it with the following command.

docker compose up --build

Interacting with the Server

To send commands to the server once it has started, use the following command on your Host machine. The below example will send "Hello World" to the game chat.

docker exec tmodloader inject "say Hello World!"

You can alernatively use the UID of the container in place of tmodloader if you did not name your configuration.

Credit to ldericher for this method of command injection to tModLoader's console.

Notes

I do not own tModLoader or Terraria. This Docker Image was created for players to easily host a game server with Docker, and is not intended to infringe on any Copyright, Trademark or Intellectual Property.