Getting Started

Getting started

Requirements

• Docker Engine with Compose, or Docker Desktop using Linux containers.
• A 64-bit AMD64 or ARM64 host environment.
• Writable storage and enough memory for your chosen world and mod pack.
• Compatible tModLoader clients for everyone joining.

1. Create the Compose file

Create an empty folder for your server. Save the following as docker-compose.yml inside it:

services:
  tmodloader:
    image: ghcr.io/crosis47/tmodloader:latest
    restart: unless-stopped
    stop_grace_period: 2m
    env_file: .env
    environment:
      TMOD_PORT: ${TMOD_PORT:-${TMOD_HOST_PORT:-7777}}
      TMOD_WEB_PORT: ${TMOD_WEB_PORT:-${TMOD_WEB_HOST_PORT:-8080}}
    healthcheck:
      start_period: ${TMOD_HEALTH_START_PERIOD:-60s}
    ports:
      - "${TMOD_PORT:-${TMOD_HOST_PORT:-7777}}:${TMOD_PORT:-${TMOD_HOST_PORT:-7777}}/tcp"
      - "${TMOD_WEB_PORT:-${TMOD_WEB_HOST_PORT:-8080}}:${TMOD_WEB_PORT:-${TMOD_WEB_HOST_PORT:-8080}}/tcp"
    volumes:
      - "./data:/data"
      - "./backups:/backups"

This uses the latest stable image, publishes the game and LAN dashboard ports, and keeps your files in data and backups beside Compose. Use dedicated writable folders: startup prepares their Linux ownership as UID/GID 1000:1000. For a fixed version or Docker Hub image, see Image tags and channels.

2. Create the settings file

Save this as .env in the same folder (not .env.txt). This starter file enables browser-managed settings; omitted options use the image defaults.

TMOD_WEB_ENABLED=1
TMOD_WEB_PORT=8080
TMOD_HEALTH_START_PERIOD=60s
TMOD_WEB_ORIGIN=

# Check supported tModLoader runtime updates at startup; 0 keeps selected runtime.
TMOD_AUTO_UPDATE=1

# Game connection and access
TMOD_PORT=7777
TMOD_MAXPLAYERS=8
TMOD_PASS=

# First world: size 1/2/3; difficulty 0 Classic, 1 Expert, 2 Master, 3 Journey
TMOD_WORLDNAME=Docker
TMOD_WORLDSIZE=3
TMOD_DIFFICULTY=1
TMOD_WORLDEVIL=random
TMOD_WORLDSEED=Docker

# Optional comma-separated Workshop IDs or collection:ID entries
TMOD_MODS=

# Minutes; 0 disables scheduled backups. Backups briefly stop the game.
TMOD_BACKUP_INTERVAL=0
TMOD_BACKUP_KEEP=7
TMOD_AUTOSAVE_INTERVAL=10

Choose your world name and game password before starting. An empty TMOD_PASS means players do not need a game password. The dashboard admin token is a separate credential. In web mode, you can later change or remove the game password through Configuration.

World size, difficulty, evil, and seed only affect newly generated worlds. The example creates a large Expert world. Use single quotes around a password containing $ or #, for example TMOD_PASS='your$password#here', to preserve it literally.

Prefer the full commented templates? Download docker-compose.yml and .env.example, saving the latter as .env, instead of using the starter blocks above. The full Compose template also includes optional secret and custom-configuration mounts.

Environment values seed web settings on first boot. Later changes to saved web settings belong in the dashboard. See Configuration for the full reference.

With the WebUI enabled, saved settings take precedence by default. Explicit TMOD_CONFIG_SOURCE=env remains available for monitoring-only deployments.

Install without the WebUI

For 3.7.3, TMOD_WEB_ENABLED=0 is the required switch. Include TMOD_CONFIG_SOURCE=env as shown below for compatibility with older 3.7.2 deployments. Replace the starter .env above with this example and customize your world, mods, and password:

TMOD_WEB_ENABLED=0
TMOD_CONFIG_SOURCE=env
TMOD_PORT=7777
TMOD_HEALTH_START_PERIOD=60s
TMOD_WORLDNAME=Docker
TMOD_MODS=
TMOD_PASS=
TMOD_MAXPLAYERS=8
TMOD_WORLDSIZE=3
TMOD_DIFFICULTY=1
TMOD_WORLDEVIL=random
TMOD_WORLDSEED=Docker
TMOD_AUTOSAVE_INTERVAL=10
TMOD_BACKUP_INTERVAL=0
TMOD_BACKUP_KEEP=7

Only the mode switch is required on 3.7.3; the other entries make the intended deployment explicit. This example selects no Workshop mods, no game password, and no scheduled backups. Before reusing existing data, replace Docker with the existing world name and supply the intended mod selection and password. Do not expect previously saved WebUI values to carry over while the WebUI is disabled. See required environment settings.

No dashboard setup is needed. You can remove the dashboard port mapping from Compose. Follow the startup commands below and check game readiness in the logs. Keep the 60-second health grace period unless measured startup time warrants a longer one. Re-enabling web-managed mode restores saved WebUI precedence, so review those saved settings first.

3. Start the container

Open a terminal in the folder containing both files. Check the configuration, then start:

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs --tail=100 --follow tmodloader

With the dashboard enabled, game startup waits for initial admin setup:

1. Find the one-time setup code in the container logs.
2. Open http://SERVER-IP:8080 from your LAN, replacing SERVER-IP with the Docker host's IP address, or http://localhost:8080 on the host itself.
3. Enter the setup code and choose an admin token: 8–256 ASCII characters, with no whitespace.
4. Confirm the token. The form shows validation and matching indicators; Create token and start server becomes available when all fields are ready. Submit, then save the token in your password manager.

The game starts automatically after setup. From 3.5.0, the first launch downloads tModLoader and its matching native .NET runtime into /data; internet access is required even with TMOD_AUTO_UPDATE=0. Later launches reuse the persistent installation. Startup runtime updates are enabled by default, including staged mod downloads and a copied-world compatibility test. These checks and initial world generation can take several minutes. Allow space for three copies of game data plus the default 1 GiB reserve. See Startup runtime updates for version controls and recovery. Ctrl+C stops following logs without stopping the container.

An incorrect setup code produces a specific error; recheck the current container logs and retry. If the connection drops, follow the form's recovery guidance. For hostnames, HTTPS proxies, or SSH tunnels, see Networking and access.

Docker health checks accept pending dashboard setup, so a healthy container at that stage does not mean the game is running. After setup, health requires both a responding dashboard and a ready game; headless deployments check the game directly. Keep TMOD_HEALTH_START_PERIOD=60s unless measured startup time requires more grace; increase it only as needed. See Container health.

4. Join the game

docker compose ps

Wait for a healthy server, then connect through tModLoader using the Docker host's address and port 7777, or your configured TMOD_PORT. Internet players need the game TCP port allowed through the host firewall and forwarded by the router.

5. Protect your progress

Keep the data and backups directories. Scheduled backups are disabled initially. Follow Backups and recovery to enable them and understand the brief game interruption.

If startup fails, begin with Troubleshooting.