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.

• 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

• 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

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.

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

# 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

Create a directory on Host machine to house the world file as well as backups.

# Making the Worlds directory and exporting it to a variable.
mkdir /path/to/worlds/directory
export TMOD_WORLDS=/path/to/worlds/directory

You can omit this, though the worlds will not be saved after your container shuts down! You have been warned.

Create a directory on the Host machine to house the Steam Workshop files for the tModLoader mods to download to.

This is optional, but including this in your configuration will greatly reduce the startup time after the mods have been downloaded from Steam.

# Making the Workshop directory and exporting it to a variable.
mkdir /path/to/workshop/directory
export TMOD_WORKSHOP=/path/to/workshop/directory

If you would rather have the server read from a configuration file, you may map the configuration file directly. Be sure to set the TMOD_USECONFIGFILE environment variable to a value of YES.

Refer to the Terraria Server Documentation on how to setup a configuration file.

# Exporting the path to the config.txt to a variable
export TMOD_CONFIGFILE=/path/to/config.txt

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

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 should be mapped to a Host machine directory 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

Assuming you map a persistant location on your Host machine to store the Workshop content, 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.

The following are all of the environment variables that are supported by the container.

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

# Execute the container
docker run -p 7777:7777 --name tmodloader --rm \
  -v $TMOD_WORLDS:/root/.local/share/Terraria/tModLoader/Worlds \
  -v $TMOD_WORKSHOP:/root/terraria-server/workshop-mods \
  -v $TMOD_CONFIGFILE:/root/terraria-server/config.txt \
  -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_USECONFIGFILE='No' \
  jacobsmile/tmodloader1.4

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

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.

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.