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

Configuration	Which settings win
TMOD_WEB_ENABLED=0	Environment values and image defaults; saved WebUI settings and passwords are ignored in 3.7.3.
TMOD_WEB_ENABLED=1, configuration source omitted or web	Saved WebUI values override matching environment values, including empty strings. Environment values seed settings not yet saved.
TMOD_WEB_ENABLED=1 and explicit TMOD_CONFIG_SOURCE=env	Compatibility option for monitoring-only deployments: environment manages game settings and the dashboard cannot edit them.

The WebUI defaults to enabled. New deployments no longer need TMOD_CONFIG_SOURCE; omit it to follow WebUI enablement. With web-managed settings, save, review, and apply changes in the dashboard. Ports, mounts, and startup runtime-update settings remain managed outside it.

After editing .env or Compose, run docker compose up -d. A plain restart does not import a changed environment. Recreating the container in web mode does not replace saved values with environment values.

Required environment variables without the WebUI

On 3.7.3, the only mode switch required to run without the dashboard is TMOD_WEB_ENABLED=0. Saved WebUI settings and the saved game password are ignored, even if an older .env still contains TMOD_CONFIG_SOURCE=web. No admin token or setup code is required. Unspecified settings use image defaults; they do not inherit your previous dashboard choices.

For a configuration that also works on 3.7.2, use both lines:

TMOD_WEB_ENABLED=0
TMOD_CONFIG_SOURCE=env

Before switching an existing server, put its intended settings into .env:

Setting to review	What to supply
TMOD_WORLDNAME	Exact existing world filename without its extension; otherwise the default Docker world may load or be created.
TMOD_MODS	The server's Workshop IDs or collection:ID entries. Do not rely on the saved dashboard selection.
TMOD_PASS or TMOD_PASS_FILE	Intended game password or mounted password file. An empty password allows joining without one.
TMOD_PORT	Intended game port; current Compose uses it for both listener and publication.
Backup, autosave, restart, and Journey settings	Explicit values for any behavior that differs from image defaults. Saved WebUI choices are ignored while disabled.

For new worlds, also choose TMOD_WORLDSIZE, TMOD_DIFFICULTY, TMOD_WORLDEVIL, and TMOD_WORLDSEED; these do not alter an existing world. These settings are deployment choices, not mandatory nonempty variables. See the installation example for a copyable starting point.

Apply .env changes with docker compose up -d, then check the selected world, mods, and readiness in the logs. Saved WebUI files are retained; enabling web-managed mode again makes those saved values take precedence again, including intentionally empty values. Review them before returning to web mode.

Change the game password

In web mode, open Configuration → Server configuration → Server password and choose Change password or Remove password. Enter a new value when changing it, then Save staged settings, review the saved draft, and Review & apply. Applying restarts the game and disconnects players. Keep existing password leaves any saved password draft unchanged.

The password is hidden and is never returned by the settings API. In web-managed mode, a saved dashboard password, including an empty value, overrides TMOD_PASS and TMOD_PASS_FILE on later starts. Removing the password lets players join without one. This does not change the dashboard admin token. In env mode, manage the password through the environment or mounted password file; custom configurations supply it in their own file.

The 3.7.5 Configuration interface with a demonstration password entry. No live password was changed. Select the image to view full size.

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 cannot be combined with active web-managed mode. With the WebUI disabled, 3.7.3 uses environment-managed mode even if a stale source value says web. 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 with the supplied Compose file. Use generated configuration for dashboard-managed settings, world switching, and playthrough loading.

Scheduling

In web mode, open Configuration → Scheduling to manage Backup scheduling & retention, Autosave, and Scheduled restarts. Save staged settings, review the differences, and apply them to activate the schedule. In env mode, edit the corresponding .env values and recreate the container.

Backup and restart modes are Disabled, Every X minutes, Every X days, Daily, Weekly, and Monthly. Calendar modes use a 24-hour time and an IANA timezone such as America/New_York; the next-run status also shows your browser's local time. Monthly days beyond the end of a month use its last day. When daylight saving time changes, repeated times use the first occurrence and missing times shift forward by the clock-change gap.

For example, select Daily backups at 03:00 in UTC, and Weekly restarts on Sunday at 04:00 in America/New_York. These are independent schedules. Restarts wait for a healthy game and other operations to finish. The scheduled time starts the warning; the game saves and stops after the configured delay. Scheduled restarts preserve running settings and the installed runtime without applying drafts or checking updates. Players disconnect during backups and restarts; autosave keeps them connected.

Restart countdown values are remaining seconds, such as 300,60,10; values above the warning delay are skipped. An empty countdown disables countdown announcements, and an empty restart message omits the initial announcement. On Overview, review Postpone restart or Skip once / cancel countdown before saving starts. Postpone accepts 1–1440 minutes; skip affects this occurrence or cancels a manual countdown while keeping the recurring schedule. See immediate controls.

Autosave defaults to every 10 minutes. Its message can be empty for silent saves; autosave does not create a backup archive. Docker shutdown uses a separate warning message and delay. Keep stop_grace_period longer than shutdown delay plus shutdown timeout and overhead.

The 3.7.5 Scheduling interface captured October 2 with demonstration daily backups and weekly restarts. No live schedule was changed. Select the image to view full size.

Defaults reference

These defaults reflect the 3.7.5 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.

WebUI only? marks variables that are useful only with TMOD_WEB_ENABLED=1. No means the setting also applies without the dashboard; TMOD_WEB_ENABLED itself is the enable/disable switch. TMOD_CONFIG_SOURCE only overrides management while WebUI is enabled; it is ignored while disabled. Game settings marked No still follow the saved-WebUI precedence described above when web-managed mode is active. Workshop API keys support dashboard search and dependency checks; ordinary startup downloads do not require them.

Web dashboard

Setting	Default	Purpose	WebUI only?
TMOD_WEB_ENABLED	1	1 enables the dashboard and first-run admin setup; 0 disables both.	No
TMOD_CONFIG_SOURCE	web	Optional compatibility override, no longer in the template. Omitted means web when the WebUI is enabled; disabled WebUI always uses env. Explicit env keeps an enabled dashboard monitoring-only.	Yes
TMOD_WEB_PORT	8080	Dashboard listener and published port in current Compose, from 1 to 65535. Recreate after changing it.	Yes
TMOD_HEALTH_START_PERIOD	60s	Supplied Compose startup grace period. Increase only when measured startup time requires it.	No
TMOD_WEB_HOST_PORT	8080	Compatibility fallback used only when TMOD_WEB_PORT is unset or empty in current Compose; not in the recommended template.	Yes
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.	Yes
TMOD_WEB_TRUSTED_PROXY	(empty)	Optional proxy IP, service name, or network alias as seen by the container; DNS names are resolved for each request and must match the connecting peer. 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.	Yes
TMOD_WEB_TOKEN_FILE	(empty)	Optional path inside the container to an existing Argon2id admin hash file.	Yes
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.	Yes

Game network and access

Setting	Default	Purpose	WebUI only?
TMOD_PORT	7777	Game listener and published TCP port in current Compose.	No
TMOD_HOST_PORT	7777	Compatibility fallback when TMOD_PORT is unset or empty; not in the recommended template.	No
TMOD_USECONFIGFILE	No	Yes uses the mounted customconfig.txt; No uses generated server configuration.	No
TMOD_MOTD	A tModLoader server powered by Docker!	Message displayed to players when they join the server.	No
TMOD_PASS	(empty)	Initial game password; empty or N/A disables it. Saved web passwords take precedence. Separate from the admin token.	No
TMOD_PASS_FILE	(empty)	Optional game-password file path inside the container; mount the file separately.	No
TMOD_MAXPLAYERS	8	Maximum simultaneous players allowed, from 1 to 255.	No
TMOD_LANGUAGE	en-US	Language code for server messages, such as en-US.	No

Recommended TMOD_PORT and TMOD_WEB_PORT values take precedence over the old host-port names. Older or custom Compose files may still publish a different host port; inspect the actual mapping when upgrading.

World selection and generation

Setting	Default	Purpose	WebUI only?
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.	No
TMOD_WORLDSIZE	3	Used only when creating a world: 1 small, 2 medium, 3 large.	No
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.	No
TMOD_WORLDSEED	Docker	Seed used when generating a new world. Changing it does not regenerate the current world.	No
TMOD_DIFFICULTY	1	Used when creating a world: 0 Classic, 1 Expert, 2 Master, 3 Journey.	No

Mods and Workshop

Setting	Default	Purpose	WebUI only?
TMOD_MODS	(empty)	Comma-separated Workshop mod IDs or collection:ID entries. Removing an entry disables it on managed startup but keeps cached downloads.	No
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.	No
TMOD_COLLECTION_MAX_ITEMS	1000	Maximum items allowed while expanding Workshop collections, from 1 to 1000. Limits unexpectedly large collections.	No
TMOD_DOWNLOAD_RETRIES	3	Maximum attempts for transient Steam Workshop download failures, from 1 to 20.	No
TMOD_DOWNLOAD_RETRY_DELAY	10	Time to wait between failed download attempts, from 0 to 600 seconds.	No

Backups and autosave

Setting	Default	Purpose	WebUI only?
TMOD_BACKUP_INTERVAL	0	Minutes between backups in interval mode; 0 disables that mode. 1440 runs approximately every 24 hours. The interval resets on container start or after a manual backup.	No
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.	No
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.	No
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.	No
TMOD_BACKUP_MODE	interval	Choose disabled, minutes, every X days, daily, weekly, or monthly. Interval mode preserves the existing backup interval. Cold backups disconnect players, save, archive, and restart the game.	No
TMOD_BACKUP_DAYS	7	Used in days mode. Each day is 24 hours. The timer resets on container startup, configuration apply, and after any backup attempt.	No
TMOD_BACKUP_WEEKDAY	sunday	Used for weekly backups at the selected backup time and timezone.	No
TMOD_BACKUP_MONTHDAY	1	Used for monthly backups. Choose 1 through 31; shorter months use their last day.	No
TMOD_BACKUP_TIME	03:00	Daily, weekly, and monthly backups use this 24-hour HH:MM time. Busy or unhealthy servers defer the backup.	No
TMOD_BACKUP_TIMEZONE	UTC	Use UTC or an IANA timezone such as America/New_York. Missing daylight-saving times shift forward; repeated times use their first occurrence.	No
TMOD_AUTOSAVE_MESSAGE	Scheduled world save starting.	Chat message sent before each scheduled save. Leave empty to save silently. The autosave interval controls the schedule; 0 disables scheduled saves. Save the draft and apply to activate changes.	No

Scheduled restarts

Setting	Default	Purpose	WebUI only?
TMOD_RESTART_MODE	disabled	Choose disabled (default), minutes, every X days, daily, weekly, or monthly. Save the draft and apply to activate changes. Busy or unhealthy servers defer the restart until ready.	No
TMOD_RESTART_INTERVAL	0	Used in interval mode only. 0 disables interval restarts; 1440 is approximately every 24 hours. The timer resets whenever the game starts, including after backups or applying settings.	No
TMOD_RESTART_DAYS	7	Used in every-X-days mode. Enter 1 through 3650; each day is exactly 24 hours. The timer resets whenever the game starts, including after backups or applying settings. It does not use the calendar time or timezone.	No
TMOD_RESTART_WEEKDAY	sunday	Used in weekly mode. Choose the weekday on which the restart warning begins, at the selected time in the selected timezone.	No
TMOD_RESTART_MONTHDAY	1	Used in monthly mode. Choose 1 through 31. If a month has fewer days, use its last day: 31 becomes February 28 or 29, for example.	No
TMOD_RESTART_TIME	04:00	Used for daily, weekly, and monthly schedules. Enter HH:MM in 24-hour format, such as 04:00, in the restart timezone below. The warning starts at this time; the game stops after the warning delay.	No
TMOD_RESTART_TIMEZONE	UTC	Used for daily, weekly, and monthly schedules. Use UTC or an IANA timezone such as America/New_York. A skipped daylight-saving time shifts forward by the clock-change gap; a repeated time runs at its first occurrence only.	No
TMOD_RESTART_DELAY	60	Wait after the scheduled restart announcement before saving and stopping the game. Default: 60; 0 restarts immediately. This delay is separate from the Docker shutdown warning delay.	No
TMOD_RESTART_COUNTDOWN	300,60,10	Comma-separated remaining times, such as 300,60,10. Warnings longer than the restart delay are skipped. Leave empty to disable countdown chat messages; the initial announcement is controlled separately.	No
TMOD_RESTART_MESSAGE	Scheduled server restart soon. Please prepare to disconnect.	Chat message sent when a scheduled restart becomes due, before the warning delay. Leave empty to omit the announcement. Players will still disconnect when the game restarts.	No

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	WebUI only?
TMOD_AUTO_UPDATE	1	Check and stage supported runtime updates at startup. 0 keeps an installed runtime and uses in-place Workshop startup behavior; first installation still requires internet access.	No
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.	No
TMOD_UPDATE_VERSION	(empty)	Pin an exact supported tModLoader release. Older versions require checkpoint recovery rather than a downgrade pin.	No
TMOD_UPDATE_MIN_FREE_MB	1024	Extra free data-volume space in MiB, beyond space for three copies of game data.	No
TMOD_UPDATE_TEST_TIMEOUT	600	Maximum copied-world compatibility test/live readiness wait in seconds. Increase for large modded worlds.	No

Runtime and diagnostics

Setting	Default	Purpose	WebUI only?
TMOD_SHUTDOWN_MESSAGE	Server is shutting down NOW!	Chat message sent to players when Docker requests a graceful container shutdown.	No
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 TMOD_SHUTDOWN_DELAY and shutdown overhead.	No
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.	No
TMOD_CRASH_LOG_LINES	200	Number of raw console lines replayed when the game fails. 0 disables crash replay; debug already shows raw output.	No
TMOD_SECURE	0	0 disables Terraria’s additional cheat checks; 1 enables them. This is not authentication or a firewall.	No
TMOD_NPCSTREAM	60	Controls NPC streaming to clients, from 0 to 1000. Leave the default unless tuning network behavior.	No
TMOD_UPNP	0	0 disables automatic router port mapping; 1 requests it. Docker port publishing and firewall rules still need host configuration.	No
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.	No
TMOD_SHUTDOWN_DELAY	3	Wait after the shutdown announcement before requesting save-and-exit when Docker stops the container. Default: 3; 0 skips the delay. Keep Docker stop_grace_period longer than this delay plus the graceful shutdown timeout and shutdown overhead. Dashboard restarts and backups use their own stop flow.	No
TMOD_LOG_RETENTION_DAYS	30	Remove archived console logs older than this many days. Default: 30; 0 disables age-based cleanup. The current and previous console logs and tModLoader own logs are kept.	No
TMOD_LOG_HISTORY_MAX_MB	512	Remove oldest archived console logs until history fits this budget. Default: 512; 0 disables the size limit. Current and previous console logs are separate from this budget.	No
TMOD_LOG_ROTATE_MB	64	Rotate the current console log at this size so one long server session cannot grow it indefinitely. Default: 64. Cleanup runs at startup, rotation, and periodically while output is received.	No

Journey permissions

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

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 TMOD_SHUTDOWN_DELAY and 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.