Networking and Access

Networking and access

Game connections

Setting	Default	Purpose	WebUI only?
TMOD_PORT	7777	Published and internal game port with current Compose	No

The 3.7.3 Compose template uses TMOD_PORT for both the listener and published game port. TMOD_HOST_PORT is a compatibility fallback only when the recommended value is unset or empty. Older or custom mappings with separate ports remain supported. For internet connections, forward the host port on the router and allow it through the host firewall. Players connect to the Docker host's reachable address, not the container's internal address.

TMOD_UPNP=1 requests automatic router mapping but does not replace Docker port publishing or host firewall configuration.

Private dashboard access

The supplied Compose file publishes the admin port on the Docker host for LAN access. Open http://SERVER-IP:8080 from another LAN computer, or http://localhost:8080 on the Docker host. Allow the chosen dashboard port through the host firewall for the intended clients.

Since 3.1.0, HTTP is accepted from RFC 1918 client addresses (10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16) and loopback. Other source addresses require HTTPS on every request. This does not include every VPN address range or IPv6 private range.

Leave TMOD_WEB_ORIGIN empty when browsing to a literal server IP or localhost; the browser port is handled automatically. For a DNS hostname, set the exact origin, such as http://terraria.example.lan:8080, and recreate the container. Setup-code authentication, admin-token authentication, and same-origin checks still apply.

Optional localhost-only access

To restrict the host listener to loopback, replace the dashboard port mapping in Compose with:

- "127.0.0.1:${TMOD_WEB_PORT:-${TMOD_WEB_HOST_PORT:-8080}}:${TMOD_WEB_PORT:-${TMOD_WEB_HOST_PORT:-8080}}/tcp"

For a remote host with SSH access, run this on your own computer, replacing your-server with your SSH destination:

ssh -L 8080:127.0.0.1:8080 your-server

Keep that connection open and browse to the same localhost URL. Leave TMOD_WEB_ORIGIN empty for automatic localhost/port handling, or ensure an explicitly configured origin matches the browser URL.

HTTPS reverse proxy

Set TMOD_WEB_ORIGIN to the exact HTTPS browser origin, including any non-default port. Set TMOD_WEB_TRUSTED_PROXY to the proxy IP, service name, or network alias as seen by the container (service names and aliases require 3.7.4 or newer). Names are resolved for each request; the connecting peer must match a resolved address. If DNS resolution fails, forwarded headers are rejected. The proxy must preserve the browser's Host header, overwrite X-Forwarded-For with one original client IP, and set X-Forwarded-Proto to https for HTTPS requests. Wildcards and multi-hop forwarded-address chains are not supported. Forwarded headers from an untrusted peer are rejected.

For a proxy service named caddy on the same Docker network, for example:

TMOD_WEB_ORIGIN=https://terraria.example.com
TMOD_WEB_TRUSTED_PROXY=caddy

Replace the example origin and service name with your own. The name must resolve inside the tModLoader container.

Keep the backend reachable only by the intended proxy or local clients. A proxy in another container needs an explicitly configured network path to the dashboard; its own localhost is not the Docker host. Recreate the container after changing these settings.

Change the dashboard port

For access on port 8081, set:

TMOD_WEB_PORT=8081
TMOD_WEB_ORIGIN=

Then run docker compose up -d and open the server IP or localhost on port 8081. The current Compose file changes both the published and internal dashboard ports to 8081. If you explicitly configured an origin, update its port to match the browser URL.

Set TMOD_WEB_PORT (1–65535) for the dashboard port. TMOD_WEB_HOST_PORT is only a compatibility fallback when it is unset or empty. Older Compose files must replace their fixed container port with ${TMOD_WEB_PORT:-8080}. Reverse proxies connecting directly to the container must use the new internal port. The browser origin still uses the published/proxy URL, not the internal port. Recreate the container after changing either port.

Multiple servers

Use a separate deployment directory and Compose project for each server, with its own .env, data, and backups. Choose distinct host game and dashboard ports.

A second deployment can use:

TMOD_PORT=7778
TMOD_WEB_PORT=8081
TMOD_WEB_ORIGIN=

Players join that server on port 7778, and the supplied Compose file also sets its internal game listener to 7778. Custom Compose deployments may still reuse an internal game port with distinct host mappings. Never point both servers at the same live data directory.