.env.example

# Copy this file to .env next to docker-compose.yml.
# Recreate the container with docker compose up -d after changing .env.
# WebUI is enabled by default. Set TMOD_WEB_ENABLED=0 to run without it.

# ======================================================================
# 1. WEB UI - ENABLED BY DEFAULT
# ======================================================================
# Start with docker compose up -d, then read docker compose logs tmodloader.
# Open http://SERVER-IP:8080 and enter the one-time setup code from the logs.
# Choose your admin token; the game waits until first-run setup is complete.
# To skip the WebUI and setup entirely, set TMOD_WEB_ENABLED=0.
# With WebUI disabled, environment settings win and saved WebUI settings are ignored.
# WebUI enabled: manage application settings in the dashboard.
# In web mode, saved WebUI values override matching environment values after
# first boot. Edit those values in the UI, then review/apply to restart the game.
# No secret mount is required for first-run setup.
# MAIN SWITCH: 0 disables the WebUI; 1 enables it.
TMOD_WEB_ENABLED=1
# Docker startup grace period. Increase only if measured startup time requires it.
TMOD_HEALTH_START_PERIOD=60s
# Dashboard listening and published port in the supplied Compose configuration.
# Not editable in the WebUI.
TMOD_WEB_PORT=8080
# Leave empty to use the server IP automatically, including custom ports.
# For a hostname/reverse proxy, set the exact browser URL (scheme and port).
# HTTP is allowed from RFC 1918 client IPs and loopback; other clients need HTTPS.
TMOD_WEB_ORIGIN=
# Optional proxy IP or service name/network alias on a shared Docker network.
# Example: reverse-proxy. Never use a wildcard, URL, port, or subnet.
# The proxy must overwrite X-Forwarded-For with one client IP and
# X-Forwarded-Proto with http or https, and preserve the browser Host header.
TMOD_WEB_TRUSTED_PROXY=
# Optional existing Argon2id hash file INSIDE the container (not plaintext).
# Leave empty for first-run setup; otherwise enable its matching Compose mount.
TMOD_WEB_TOKEN_FILE=
# Optional Steam API key file INSIDE the container; enable its matching mount.
# Alternatively enter and validate a key on Workshop; its private saved file wins.
# Search and dependency checks need a key; URL/ID lookup and profiles need no key.
TMOD_WORKSHOP_KEY_FILE=

# Startup runtime updates (container recreation applies these settings).
# Checks and stages the latest supported release, mods and copied-world test.
# 0 keeps the selected runtime and the original in-place Workshop startup behavior.
# First startup always downloads tModLoader and .NET into /data.
# Set 0 to reuse that installation without subsequent automatic updates.
TMOD_AUTO_UPDATE=1
# Empty uses the image's stable/preview channel. To override, uncomment one:
# TMOD_UPDATE_CHANNEL=stable
# TMOD_UPDATE_CHANNEL=preview
# Optional exact release pin. Older versions require checkpoint recovery, not downgrade.
TMOD_UPDATE_VERSION=
# Extra free data-volume space required beyond three copies of game data.
TMOD_UPDATE_MIN_FREE_MB=1024
# Maximum copied-world test/live readiness wait, in seconds.
TMOD_UPDATE_TEST_TIMEOUT=600

# ======================================================================
# 2. GAME NETWORK & ACCESS
# ======================================================================
# Game listening port inside the container and published port on the Docker host.
# Each server needs its own available port (for example, 7777 or 7778).
# Players connect to this port; forward the same TCP port on your router if needed.
TMOD_PORT=7777
# USECONFIGFILE=Yes uses the customconfig.txt mount shown in Compose.
# Its listening port must match TMOD_PORT for the supplied Compose mapping.
TMOD_USECONFIGFILE=No
TMOD_MOTD=A tModLoader server powered by Docker!
# Initial game password, not the WebUI admin token. Empty/N/A disables it.
# In web mode, a password saved in Configuration overrides this and TMOD_PASS_FILE.
TMOD_PASS=
# Optional game-password file INSIDE the container; enable its Compose mount.
TMOD_PASS_FILE=
TMOD_MAXPLAYERS=8
TMOD_LANGUAGE=en-US

# ======================================================================
# 3. WORLD SELECTION & GENERATION
# ======================================================================
# WORLDNAME selects a saved world or creates one if missing.
# Size: 1 small, 2 medium, 3 large. Difficulty: 0 Classic, 1 Expert, 2 Master, 3 Journey.
# Evil: random, corruption, crimson. Size/seed/evil/difficulty affect NEW worlds only.
# Choose an unused world name to generate a world with different options.
TMOD_WORLDNAME=Docker
TMOD_WORLDSIZE=3
TMOD_WORLDEVIL=random
TMOD_WORLDSEED=Docker
TMOD_DIFFICULTY=1

# ======================================================================
# 4. MODS & WORKSHOP
# ======================================================================
# MODS accepts comma-separated Workshop IDs and collection:ID entries.
# Offline policy: use-cache permits cached mods; strict requires successful updates.
# Download retry delay is in seconds; collection maximum limits expanded items.
TMOD_MODS=
TMOD_MOD_OFFLINE_POLICY=use-cache
TMOD_COLLECTION_MAX_ITEMS=1000
TMOD_DOWNLOAD_RETRIES=3
TMOD_DOWNLOAD_RETRY_DELAY=10

# ======================================================================
# 5. BACKUPS & AUTOSAVE
# ======================================================================
# Intervals are in minutes; 0 disables scheduling. 1440 = once every 24 hours.
# Backups save, stop and restart the game, disconnecting players.
# KEEP is the archive count; MIN_FREE_MB reserves disk space before backup.
# Autosave saves the live world; it does not create a backup archive.
# AUTOSAVE_INTERVAL: whole minutes, default 10; 0 disables scheduled saves.
# Web-managed servers: Configuration > Backups & autosave, then save/apply.
TMOD_BACKUP_INTERVAL=0
# Backup modes: disabled, interval (default), days, daily, weekly, monthly.
# Keep interval=0 to leave scheduled backups off. Calendar schedules use TIME/TIMEZONE.
TMOD_BACKUP_MODE=interval
TMOD_BACKUP_DAYS=7
TMOD_BACKUP_WEEKDAY=sunday
TMOD_BACKUP_MONTHDAY=1
TMOD_BACKUP_TIME=03:00
TMOD_BACKUP_TIMEZONE=UTC
TMOD_BACKUP_KEEP=7
TMOD_BACKUP_MIN_FREE_MB=1024
TMOD_AUTOSAVE_INTERVAL=10
# Leave empty to disable the chat announcement while keeping scheduled saves.
TMOD_AUTOSAVE_MESSAGE=Scheduled world save starting.

# ======================================================================
# 6. RUNTIME & DIAGNOSTICS
# ======================================================================
# Shutdown delay and timeout are in seconds. Keep Compose stop_grace_period
# longer than their sum plus shutdown overhead. Delay 0 skips the warning wait.
# Log level: quiet, normal, debug. CRASH_LOG_LINES controls failure diagnostics.
# SECURE is additional cheat checking (0/1); UPNP is automatic port mapping (0/1).
# NPCSTREAM and PRIORITY tune the native server; retain defaults unless needed.
TMOD_SHUTDOWN_MESSAGE=Server is shutting down NOW!
TMOD_SHUTDOWN_DELAY=3
TMOD_SHUTDOWN_TIMEOUT=90
TMOD_LOG_LEVEL=normal
TMOD_CRASH_LOG_LINES=200
# Console archive cleanup: 0 disables the age/size limit individually.
# Current and previous console logs, game logs, and player history are excluded.
TMOD_LOG_RETENTION_DAYS=30
TMOD_LOG_HISTORY_MAX_MB=512
# Rotate active console output at this size (MiB); 1-1024.
TMOD_LOG_ROTATE_MB=64
TMOD_SECURE=0
TMOD_NPCSTREAM=60
TMOD_UPNP=0
TMOD_PRIORITY=1

# Scheduled game restarts: disabled, interval, days, daily, weekly, or monthly.
# Busy/unhealthy servers defer the restart until ready.
# Saves and restarts the game without applying drafts or checking updates.
# WebUI: Configuration > Scheduled restarts; save the draft and apply.
TMOD_RESTART_MODE=disabled
# Interval mode: minutes; 0 disables. Each game start resets the interval.
TMOD_RESTART_INTERVAL=0
# Days mode: 1-3650 periods of 24 hours; resets at each game start.
TMOD_RESTART_DAYS=7
# Weekly mode: monday, tuesday, wednesday, thursday, friday, saturday, sunday.
TMOD_RESTART_WEEKDAY=sunday
# Monthly mode: 1-31; use the month's last day when this day does not exist.
TMOD_RESTART_MONTHDAY=1
# Daily/weekly/monthly: 24-hour HH:MM and IANA timezone (e.g. America/New_York).
# Warning begins at this time; the game stops after RESTART_DELAY seconds.
TMOD_RESTART_TIME=04:00
TMOD_RESTART_TIMEZONE=UTC
# Seconds between announcement and save-and-exit; 0 skips the wait.
TMOD_RESTART_DELAY=60
# Remaining seconds at which to announce a countdown. Values above DELAY are skipped.
# Empty disables countdown announcements independently of the initial message.
TMOD_RESTART_COUNTDOWN=300,60,10
# Empty omits the announcement. Players still disconnect during restart.
TMOD_RESTART_MESSAGE=Scheduled server restart soon. Please prepare to disconnect.

# ======================================================================
# 7. JOURNEY PERMISSIONS
# ======================================================================
# Journey worlds only. Each permission: 0 locked, 1 host only, 2 everyone.
# These control who may use each power; they do not convert a world to Journey.
TMOD_JOURNEY_SETFROZEN=0
TMOD_JOURNEY_SETDAWN=0
TMOD_JOURNEY_SETNOON=0
TMOD_JOURNEY_SETDUSK=0
TMOD_JOURNEY_SETMIDNIGHT=0
TMOD_JOURNEY_GODMODE=0
TMOD_JOURNEY_WIND_STRENGTH=0
TMOD_JOURNEY_RAIN_STRENGTH=0
TMOD_JOURNEY_TIME_SPEED=0
TMOD_JOURNEY_RAIN_FROZEN=0
TMOD_JOURNEY_WIND_FROZEN=0
TMOD_JOURNEY_PLACEMENT_RANGE=0
TMOD_JOURNEY_SET_DIFFICULTY=0
TMOD_JOURNEY_BIOME_SPREAD=0
TMOD_JOURNEY_SPAWN_RATE=0

# Operator commands (run on the Docker host):
#   docker compose logs --tail=100 --follow tmodloader
#   docker compose exec --user tml:tml -T tmodloader inject "save"
#   docker compose exec --user tml:tml -T tmodloader tmod-backup backup
# Startup repairs ./data and ./backups ownership, then runs as UID/GID 1000:1000.