crosis47/tmodloader repository overview

⁠tModLoader Dedicated Server Container

Updated 2026-10-17 10:55 UTC · Refreshed hourly · Metric definitions⁠

Run a modded Terraria server in Docker, with a built-in web dashboard for managing worlds, Workshop mods, players, and backups. Keep your server's data across container updates and manage it from your browser or Docker Compose.

This independently maintained project has its own features, fixes, and releases. It is not affiliated with Re-Logic or the tModLoader team.

Container images⁠ · Docker Hub⁠ · Releases⁠ · Changelog⁠

⁠Latest release changes

⁠3.8.0⁠ - 2026-10-17

⁠Added

• Optionally save selected mod config files in a mod profile and restore their snapshots during the reviewed restart, with disk-change checks and per-file undo history.
• Preview and copy a local support report containing versions, enabled mods, and recent errors, with sensitive details removed before preview.
• Add an optional dashboard support report field to the bug report template, with manual log collection as a fallback.
• Discover mod configuration files outside ModConfigs, filter by folder, and search filenames in the dashboard editor.
• Review changes before saving, restore the previous saved version, and recover from concurrent disk edits with setting-level JSON merge choices and a syntax-repair step.
• Add dashboard links to the wiki, bug report template, and feature request template.
• Show release highlights after dashboard sign-in following a container upgrade, remember dismissal in persistent storage, and let administrators reopen them from the overview.

⁠Fixed

• Normalize editor line endings when detecting unsaved changes so files with identical content can be opened reliably.
• Validate edited and on-disk JSON before comparison, reject duplicate settings, and enable Review & Save only when the editor has changes.

Full changelog⁠ · All releases and preview notes⁠

⁠What it includes

• Web dashboard: see server health, loaded mods, connected players, and recent activity; send commands through an interactive console and cancel saved drafts. Preview and copy a support report with sensitive values removed before review.
• Mod configuration editor: edit existing UTF-8 configuration files with syntax checks for JSON, YAML, TOML, INI, and XML. Other text formats can be edited without syntax validation. Restart the server to load saved changes.
• World cleanup: delete unused worlds after confirmation; running and draft-selected worlds are protected. Deletion includes their local backup files.
• Worlds and playthroughs: create or switch worlds, save mod profiles, and pair a world with its settings and mod selection for later use. Profiles can also snapshot selected mod config files for restoration during review and restart.
• Steam Workshop management: download mods and collections, look up Workshop URLs or IDs without an API key, and reuse cached content when Steam is unavailable. Workshop search requires a Steam API key.
• Backups and recovery: create or schedule backups, verify archives, and restore from the dashboard. Backups briefly stop the game and disconnect players.
• Persistent server data: worlds, mods, settings, and logs survive container replacement. The game and dashboard run as a dedicated non-root user.
• AMD64 and ARM64 support: Linux images for both architectures, with automated build checks and real-server startup tests before publication.

⁠Image tags and updates

Read image tags and updates in the full documentation⁠

⁠Dashboard gallery

Read dashboard gallery in the full documentation⁠

⁠Getting started

You need Docker Engine with Compose or Docker Desktop, a 64-bit AMD64 or ARM64 Linux container environment, and enough memory and disk space for your mod pack. Players need tModLoader clients compatible with the server's version and mods.

⁠1. Get the files

Clone this repository, or download docker-compose.yml⁠ and .env.example⁠ into the same folder.

git clone https://github.com/Crosis47/tmodloader.git
cd tmodloader

Copy .env.example to .env:

cp .env.example .env

On Windows PowerShell, use Copy-Item .env.example .env instead.

⁠2. Choose how to manage settings

Open .env. For browser-based configuration, set:

TMOD_WEB_ENABLED=1

This enables settings edits, world selection, and loading profiles and playthroughs in the dashboard. Environment values seed the initial settings; afterward, saved web values take precedence. Save changes in the dashboard, then use Review & apply to apply them and restart the game.

Set TMOD_WEB_ENABLED=0 to manage settings through .env and run without the dashboard or its setup step. Existing installations can explicitly retain TMOD_CONFIG_SOURCE=env to keep environment-managed settings with dashboard monitoring, console, and backup controls.

Review the essential settings⁠ below before starting, particularly the game password, world name, and mods.

Server passwords can be changed or removed in Configuration when web management is enabled. Save the password as a draft, then review and apply to restart the game. Passwords are never returned by the settings API; the protected server data stores the value needed to generate the game configuration. A saved dashboard password (including an empty value) overrides the Compose password or password file on later starts.

⁠3. Start and complete setup

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

With the dashboard enabled, the game waits for first-run admin setup:

1. Find the one-time setup code in the container logs.
2. Open http://SERVER-IP:8080 from your home network, or http://localhost:8080⁠ on the Docker host.
3. Enter the code and choose an admin token (8–256 ASCII characters, no whitespace). Save it in your password manager; use it to sign in afterward.

The container saves a hashed credential in the persistent data directory and continues startup automatically. First-time mod downloads and world generation can take several minutes. Press Ctrl+C to stop following logs without stopping the server.

HTTP works for clients in 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16 (RFC 1918), plus loopback. Other sources, including non-loopback IPv6, require HTTPS for setup and all dashboard access. HTTP traffic is unencrypted; use it only on a trusted network. The server checks the client source IP, not the URL.

Leave TMOD_WEB_ORIGIN empty when opening the server IP. For a hostname, set it to the exact browser origin. For HTTPS through a reverse proxy, also set TMOD_WEB_TRUSTED_PROXY to that proxy's IP as seen by the container, or its service name/network alias (for example, reverse-proxy) on a shared Docker network. Hostnames are resolved for each request; failed lookups do not trust forwarded headers. Use a name controlled by you on a trusted network. URLs, ports, wildcards, and subnets are not accepted. The proxy must preserve Host and overwrite X-Forwarded-For with the actual single client IP and X-Forwarded-Proto with http or https. Multi-proxy header chains are rejected. Restrict backend access to the proxy when publishing it.

Docker forwarding or another gateway can hide the original source IP behind a private address. This rule can only classify the IP the container actually sees; do not directly port-forward the HTTP dashboard to the internet. Use the HTTPS proxy with the trusted-proxy setting to preserve the original client identity.

⁠4. Join the server

Check readiness in the dashboard or run:

docker compose ps

Once the server is healthy, connect from tModLoader to your Docker host's address on port 7777 (or your chosen TMOD_PORT). Allow that TCP port through the host firewall and forward it on your router if players connect over the internet.

⁠Essential settings

Read essential settings in the full documentation⁠

⁠Data and backups

Read data and backups in the full documentation⁠

⁠Help and project information

For startup or connection problems, begin with docker compose ps and docker compose logs --tail=200 tmodloader. Include relevant logs with an issue report⁠, removing private information first.

• Configuration template⁠
• Release history⁠
• Contributing and development⁠
• Security reporting⁠
• Unraid installation and templates⁠
• License⁠

⁠Credits

Built on tModLoader⁠ for Terraria⁠. Inspired by JACOBSMILE/tmodloader1.4⁠. Thanks also to ldericher⁠, rfvgyhn⁠, guillheu⁠, and FlorentLM⁠ for their earlier work.

Container code and scripts are distributed under LICENSE.md⁠. Terraria, tModLoader, and bundled third-party tools retain their respective licenses.

The update card offers an opt-in Announce new tModLoader versions in game chat setting. It saves immediately without a restart, defaults to off, and sends one announcement per newly detected release while the game is healthy. The administration service checks in the background even without an open dashboard, using the existing release-check cache. Disabling and re-enabling the option does not repeat an already announced release.

⁠Dashboard appearance

Use the Theme selector in the header to choose Slate & Teal, Forest, Ocean, Amethyst, Copper, Solarized, Nord, or Rose Pine. The sun/moon button switches between light and dark mode. Both choices are remembered in this browser; initial light/dark mode follows your system preference.

For GitHub API rate limits during release discovery, optionally provide TMOD_GITHUB_TOKEN as a runtime environment variable. Public release metadata requires no additional repository permissions. It is used only for GitHub API requests, is not a dashboard setting, and is not included in image builds. CI smoke tests use their temporary workflow token automatically.

With TMOD_WEB_ENABLED=0, settings are environment-managed even if TMOD_CONFIG_SOURCE=web remains set. Saved WebUI settings and game passwords are ignored but retained for when WebUI management is enabled again.

⁠Port configuration

Set TMOD_PORT for the game (default 7777) and TMOD_WEB_PORT for the dashboard (default 8080). The supplied Compose configuration uses each setting directly for both the container listener and published host port.

For compatibility, Compose accepts TMOD_HOST_PORT and TMOD_WEB_HOST_PORT as fallbacks when their corresponding recommended setting is unset or empty. TMOD_PORT and TMOD_WEB_PORT take precedence when both names are supplied. Use the recommended names for new configurations.

If using a custom server configuration file, its game listening port must match TMOD_PORT. Custom Compose files can still map different host and container ports using Docker's normal port mapping.

⁠Container and game readiness

With WebUI enabled, Docker health checks the dashboard while first-time admin setup is waiting. After admin setup, both the dashboard and game must be healthy. A stopped or failed game reports unhealthy after Docker's configured failed checks, while the dashboard remains available for recovery. Downloads, world generation, backups, and intentional game stops can also temporarily report unhealthy; health status alone does not restart the container. The dashboard reports game readiness separately. With TMOD_WEB_ENABLED=0, Docker health checks game readiness only.

The default startup grace period is 60 seconds, with checks every 30 seconds and three failures required to report unhealthy. A successful check ends the startup grace period. Keep the default unless measured startup time requires a longer grace period, such as initial downloads or world generation in headless mode. Adjust TMOD_HEALTH_START_PERIOD in the supplied Compose .env, or Docker's --health-start-period, to suit that startup time. This is a deployment setting, not a WebUI setting.

healthcheck --container selects the appropriate check; healthcheck (or --game) always checks the game. Internal update and recovery operations use game readiness. The dashboard readiness endpoint /healthz is accessible only from container loopback and returns no credentials or game information. Deployment ports, mounts, and settings management mode remain controlled outside the dashboard.

⁠TCP listener recovery

The bundled server-only mod also manages the TCP listener lifecycle. Each accept thread owns its socket, preventing an older thread from closing a replacement listener when connection slots fill and reopen. Terraria still handles player limits, authentication, and packets. No client mod is required. This addresses listener recovery; it is not a substitute for firewall or access controls.

Upstream report: tModLoader/tModLoader#5470⁠.