Configuration

Configuration

The deployment uses .env beside docker-compose.yml. The commented configuration template is the source for the values below.

Choose who manages settings

Mode	Behavior
TMOD_CONFIG_SOURCE=env	Environment values manage game settings. Recreate the container after editing .env.
TMOD_CONFIG_SOURCE=web	Environment values seed initial settings. Saved dashboard values then override matching environment values, including intentionally empty values. Save, review, and apply changes in the dashboard.

The dashboard is independently controlled by TMOD_WEB_ENABLED, which defaults to 1 since 3.0.0. First startup waits for dashboard admin setup before starting the game. Set it to 0 to disable the dashboard and setup step for unattended game-only startup. The supplied .env.example selects TMOD_CONFIG_SOURCE=web; the application falls back to env when the variable is omitted. Set env explicitly for environment-managed settings.

Docker port mappings, mounts, credential inputs, and configuration mode remain managed outside the dashboard. After editing .env or Compose:

docker compose up -d

A plain container restart does not import a changed Compose environment. In web mode, recreating the container does not replace saved web values with new environment values.

Custom server configuration

Set TMOD_USECONFIGFILE=Yes with TMOD_CONFIG_SOURCE=env and add the optional mount from the full Compose template for customconfig.txt at /terraria-server/customconfig.txt. Custom configuration and TMOD_CONFIG_SOURCE=web cannot be combined; startup fails with that combination. The dashboard can remain enabled for monitoring and other available controls.

The custom file supplies native game settings instead of the generated configuration. Put its game password and world selection in that file; TMOD_PASS and TMOD_PASS_FILE are used by generated configuration. Its listening port must match TMOD_PORT. Use generated configuration for dashboard-managed settings, world switching, and playthrough loading.

Defaults reference

These defaults reflect the 3.4.1 configuration template. An empty value is shown as (empty). *_FILE values are paths inside the container and need matching mounts when the file is external.

For usage details, see Networking and access, Worlds and playthroughs, Mods and Workshop, and Backups and recovery.

Web dashboard

Setting	Default	Purpose
TMOD_WEB_ENABLED	1	1 enables the dashboard and first-run admin setup; 0 disables both.
TMOD_CONFIG_SOURCE	web	Template default: saved dashboard settings. Set env for environment-managed settings; env is also the fallback if omitted.
TMOD_WEB_HOST_PORT	8080	Dashboard port published on the Docker host for LAN access by supplied Compose.
TMOD_WEB_ORIGIN	(empty)	Automatically accept the server IP or localhost with its browser port. For a hostname or reverse proxy, set the exact origin, including scheme and non-default port.
TMOD_WEB_TRUSTED_PROXY	(empty)	Optional single proxy IP as seen by the container. That proxy must overwrite X-Forwarded-For with one client IP, set X-Forwarded-Proto to http or https, and preserve Host. No wildcard or proxy chain.
TMOD_WEB_TOKEN_FILE	(empty)	Optional path inside the container to an existing Argon2id admin hash file.
TMOD_WORKSHOP_KEY_FILE	(empty)	Optional Steam API key file inside the container for search and dependency checks. A key validated and saved on Workshop takes precedence.

Game network and access

Setting	Default	Purpose
TMOD_HOST_PORT	7777	TCP game port players connect to on the Docker host.
TMOD_PORT	7777	Game listener inside the container; Compose maps the host port to this port.
TMOD_USECONFIGFILE	No	Yes uses the mounted customconfig.txt; No uses generated server configuration.
TMOD_MOTD	A tModLoader server powered by Docker!	Message displayed to players when they join the server.
TMOD_PASS	(empty)	Game password; empty or N/A disables the password. Separate from the admin token.
TMOD_PASS_FILE	(empty)	Optional game-password file path inside the container; mount the file separately.
TMOD_MAXPLAYERS	8	Maximum simultaneous players allowed, from 1 to 255.
TMOD_LANGUAGE	en-US	Language code for server messages, such as en-US.

World selection and generation

Setting	Default	Purpose
TMOD_WORLDNAME	Docker	Selects the world file by name. A different name may create a new world if no matching file exists. Do not include path separators.
TMOD_WORLDSIZE	3	Used only when creating a world: 1 small, 2 medium, 3 large.
TMOD_WORLDEVIL	random	Random, Corruption, or Crimson. To change evil in the WebUI, choose an unused world name, stage the settings, and apply changes. Apply saves and stops the game, disconnects players, creates the new world, and restarts. Existing worlds are never converted; a matching name loads that world. Custom evil requires a name of at most 26 characters and seed of at most 39 characters. Special seeds and mods may generate both evils or alter generation.
TMOD_WORLDSEED	Docker	Seed used when generating a new world. Changing it does not regenerate the current world.
TMOD_DIFFICULTY	1	Used when creating a world: 0 Classic, 1 Expert, 2 Master, 3 Journey.

Mods and Workshop

Setting	Default	Purpose
TMOD_MODS	(empty)	Comma-separated Workshop mod IDs or collection:ID entries. Removing an entry disables it on managed startup but keeps cached downloads.
TMOD_MOD_OFFLINE_POLICY	use-cache	use-cache allows startup with available cached mods when Steam cannot be reached. strict fails if required update/download checks fail.
TMOD_COLLECTION_MAX_ITEMS	1000	Maximum items allowed while expanding Workshop collections, from 1 to 1000. Limits unexpectedly large collections.
TMOD_DOWNLOAD_RETRIES	3	Maximum attempts for transient Steam Workshop download failures, from 1 to 20.
TMOD_DOWNLOAD_RETRY_DELAY	10	Time to wait between failed download attempts, from 0 to 600 seconds.

Backups and autosave

Setting	Default	Purpose
TMOD_BACKUP_INTERVAL	0	0 disables scheduled backups. 1440 runs approximately every 24 hours. The interval resets on container start or after a manual backup.
TMOD_BACKUP_KEEP	7	Number of verified backup bundles to keep for this data directory and current build. Cleanup runs only after a successful backup and restart; other-build archives and recovery originals are not pruned.
TMOD_BACKUP_MIN_FREE_MB	1024	Refuse a backup before stopping the game when /backups has less free space than this threshold. 1024 means 1 GiB. This is not an archive-size estimate; 0 disables the threshold.
TMOD_AUTOSAVE_INTERVAL	10	Send a save command at this interval. 0 disables scheduled autosaves. Saves update the world in place; they do not create backup archives.

Startup runtime updates

These settings are managed through .env/Compose even in web mode. Recreate the container after changing them. See Updates and storage for compatibility tests, restart controls, and recovery.

Setting	Default	Purpose
TMOD_AUTO_UPDATE	1	Check and stage supported runtime updates at startup. 0 keeps the selected runtime and uses the original in-place Workshop startup behavior.
TMOD_UPDATE_CHANNEL	(empty)	Inherit the image's stable/preview channel; set stable or preview explicitly to override. This optional setting is commented out in the template.
TMOD_UPDATE_VERSION	(empty)	Pin an exact supported tModLoader release. Older versions require checkpoint recovery rather than a downgrade pin.
TMOD_UPDATE_MIN_FREE_MB	1024	Extra free data-volume space in MiB, beyond space for three copies of game data.
TMOD_UPDATE_TEST_TIMEOUT	600	Maximum copied-world compatibility test/live readiness wait in seconds. Increase for large modded worlds.

Runtime and diagnostics

Setting	Default	Purpose
TMOD_SHUTDOWN_MESSAGE	Server is shutting down NOW!	Chat message sent to players when Docker requests a graceful container shutdown.
TMOD_SHUTDOWN_TIMEOUT	90	How long to wait after requesting a save-and-exit before forced termination. Keep Docker’s stop_grace_period longer than this value plus shutdown overhead.
TMOD_LOG_LEVEL	normal	quiet reduces routine output; normal shows standard output; debug shows detailed output. Complete raw output remains in the persistent console log.
TMOD_CRASH_LOG_LINES	200	Number of raw console lines replayed when the game fails. 0 disables crash replay; debug already shows raw output.
TMOD_SECURE	0	0 disables Terraria’s additional cheat checks; 1 enables them. This is not authentication or a firewall.
TMOD_NPCSTREAM	60	Controls NPC streaming to clients, from 0 to 1000. Leave the default unless tuning network behavior.
TMOD_UPNP	0	0 disables automatic router port mapping; 1 requests it. Docker port publishing and firewall rules still need host configuration.
TMOD_PRIORITY	1	Server scheduling priority, from 0 (realtime) to 5 (idle). Lower values request higher priority; container permissions may limit this. Prefer the default unless diagnosing performance.

Journey permissions

Setting	Default	Purpose
TMOD_JOURNEY_SETFROZEN	0	Freeze time: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_SETDAWN	0	Set dawn: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_SETNOON	0	Set noon: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_SETDUSK	0	Set dusk: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_SETMIDNIGHT	0	Set midnight: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_GODMODE	0	God mode: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_WIND_STRENGTH	0	Wind strength: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_RAIN_STRENGTH	0	Rain strength: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_TIME_SPEED	0	Time speed: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_RAIN_FROZEN	0	Freeze rain: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_WIND_FROZEN	0	Freeze wind: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_PLACEMENT_RANGE	0	Extended placement range: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_SET_DIFFICULTY	0	Adjust difficulty: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_BIOME_SPREAD	0	Biome spread: 0 locked, 1 host only, 2 everyone.
TMOD_JOURNEY_SPAWN_RATE	0	Enemy spawn rate: 0 locked, 1 host only, 2 everyone.

All Journey permissions use 0 for locked, 1 for host only, and 2 for everyone. They affect Journey worlds only. In web mode, manage Server Journey defaults and per-world overrides on Worlds, not Configuration. Existing global permissions seed the initial defaults. Saved overrides persist across world switches and restarts; see Journey permissions.

Runtime notes

• TMOD_SHUTDOWN_TIMEOUT is in seconds. Keep Compose stop_grace_period longer than this value plus shutdown overhead; the supplied file uses two minutes for the default 90-second timeout.
• TMOD_LOG_LEVEL accepts quiet, normal, or debug. TMOD_CRASH_LOG_LINES controls how many raw console lines are replayed on game failure; 0 disables replay.
• TMOD_SECURE enables additional game cheat checks with 1; it does not provide authentication or firewall protection.
• TMOD_NPCSTREAM controls NPC streaming range. Keep its default unless investigating network behavior.
• TMOD_PRIORITY ranges from 0 (realtime) to 5 (idle). Lower values request higher priority, subject to container permissions.
• TMOD_PASS is the game password, not the dashboard token. Empty or N/A disables the game password. TMOD_PASS_FILE supplies a game-password file instead.
• World size, seed, evil, and difficulty only affect generation of a new world.