TrueNAS

tModLoader on TrueNAS

Use the tModLoader Community app for the Crosis47 container. This guide covers the Docker-based catalog app, not older Kubernetes charts or other Terraria images. The catalog definition was checked on October 12, 2026: app package 1.0.1, container 3.7.5. Your installed package may differ.

Install and complete setup

1. Find tModLoader in the Community catalog and open its installation form.
2. Review Data Storage, Backup Storage, network ports, and resource limits. Use dedicated storage for this server; the default storage type is an automatically created ixVolume. Host Path lets you select an existing dedicated path instead.
3. Leave the WebUI Port bind mode on Publish for direct LAN setup. Install the app, then open its container logs to find the one-time setup code.
4. Open the WebUI portal, or http://TRUENAS-IP:30525 with the default port. Enter the setup code and create your administrator credential. The game waits for this step on a new installation. First startup also needs internet access to install the runtime.
5. Manage worlds, mods, the player password, and schedules in the dashboard. Review and apply staged changes. Join from a compatible tModLoader client using the TrueNAS IP and game port, normally 30524.

The administrator credential and game password are separate. An empty game password allows joining without one. See dashboard setup.

Catalog defaults differ from Compose

App field	Catalog default	What it means
Game Server Port	30524 TCP, Publish	Players connect to this host port; the app also sets the game listener to this number.
WebUI Port	30525 TCP, Publish	Dashboard listener and published port; not the Compose default of 8080.
World Name	Docker	Selects an existing world or creates one if absent.
World Size	Small (1)	Initial generation default; the container template otherwise defaults to Large.
World Difficulty	Classic (0)	Initial generation default; the container template otherwise defaults to Expert.
CPU / memory limits	2 CPUs / 4096 MB	Installation defaults, not a guarantee that every mod pack fits. Adjust for your workload.

World size and difficulty do not convert an existing world. Saved dashboard settings override matching installation-form values, including the saved game password. Editing the app's initial fields later does not replace settings already saved in the WebUI. See settings ownership.

Network and dashboard modes

Use the app's Game Server Port and WebUI Port fields to change ports. Unlike the Unraid template, this catalog sets the internal listeners to the selected port numbers. Avoid duplicating TMOD_PORT, TMOD_WEB_PORT, or TMOD_WEB_ENABLED in Additional Environment Variables; the app generates these from its network fields.

WebUI Port bind mode	Result
Publish	Enables the dashboard and publishes its port for host/LAN access.
Expose	Enables the dashboard for container-network access without publishing a host port. An accessible proxy/network route is needed for setup.
None	Disables the dashboard and skips administrator setup; game settings come from the environment.

Before selecting None on an existing server, put the intended world and password in the app fields and supply mods and other non-default settings through Additional Environment Variables. Saved WebUI settings are ignored while disabled. See headless configuration and the WebUI only? column in the defaults reference.

For hostname access, add TMOD_WEB_ORIGIN with the exact browser origin, for example http://truenas.local:30525. For HTTPS proxies, also configure TMOD_WEB_TRUSTED_PROXY and the required headers described in Networking and access. Use the selected game TCP port for router forwarding; keep dashboard access private or behind the configured HTTPS proxy.

Storage and permissions

Data Storage mounts at /data and contains worlds, mods, runtime files, credentials, settings, and logs. Backup Storage mounts at /backups. Preserve both across app updates and reinstallations, and review storage-deletion choices before removing an app. Never share a live data path between server instances.

The catalog reports a root container user and grants ownership/identity capabilities for startup initialization. The image repairs ownership of the dedicated data and backup trees, then drops privileges to UID/GID 1000:1000 for the game and dashboard. Do not substitute an arbitrary app user or add PUID/PGID variables.

For Host Path storage, use dedicated datasets or folders. If startup reports permission errors, check the logs and ensure dataset ACLs allow the runtime identity to traverse and write the paths. Ownership repair does not justify changing permissions on an unrelated shared dataset. See persistent folders.

Backups and updates

Create and verify a dashboard backup before changing mods, worlds, or versions. These backups save and stop the game, disconnect players, and restart it afterward. Keep a separate copy outside the app's storage for recovery from storage loss. If taking a filesystem snapshot for recovery, stop the game first so its files are consistent.

The catalog pins the container image by version and digest. Apply catalog app updates through TrueNAS to receive newer container/dashboard code; a dashboard container-update notice does not update the catalog package. The catalog may offer a version later than the upstream project does.

Runtime updates are separate: TMOD_AUTO_UPDATE controls startup runtime checks, and the dashboard offers runtime update/recovery controls. Keeping a fixed catalog container version does not by itself pin the downloaded game runtime. See startup runtime updates.

The app configures a 120-second graceful stop period and a 60-second health-start period. Initial setup can be pending before the game is ready; inspect the container logs and dashboard rather than treating app startup alone as proof that players can join. See container health.

Multiple servers and troubleshooting

Use different published ports and separate data/backup storage for each instance. Common setup issues are an unfinished one-time setup, a hostname without a matching origin, an Expose-only dashboard with no reachable proxy, or Host Path permissions that prevent writes. Start with Troubleshooting and include the TrueNAS app package version, container version, selected bind modes, and relevant redacted logs when reporting an issue.