ludix0/terraria repository overview

⁠Terraria Dedicated Server (Docker)

English⁠ | Français⁠

⁠English

A self-hosted Terraria dedicated server running in Docker, built on cm2network/steamcmd:root. The container downloads and runs the official TerrariaServer.bin.x86_64 Linux binary via SteamCMD, then launches it as a non-root user.

⁠Requirements

• Docker Engine + Docker Compose plugin (docker compose, not the old docker-compose).
• A Steam account that actually owns Terraria — see Why do I need a Steam account?⁠ below.
• Port 7777/TCP reachable from wherever your players connect from (open it on your router/firewall and forward it to the machine running Docker if needed). Terraria only needs TCP — no UDP.

⁠1. Get the files

Option A — pull the pre-built image from Docker Hub (fastest):

docker pull ludix0/terraria:latest

Then create the two files below (docker-compose.yml and .env) yourself in an empty folder, and skip straight to step 3.

Option B — clone from GitHub and build the image yourself:

git clone <URL-of-this-repository>
cd terraria
docker build -t ludix0/terraria:latest .

⁠2. Configure — docker-compose.yml and .env

Create a docker-compose.yml like this:

services:
  terraria:
    image: ludix0/terraria:latest
    container_name: terraria
    restart: unless-stopped
    volumes:
      - ./filesServer:/home/steam/terraria_server
      - ./saves:/home/steam/terraria_saves
      - ./steamcmd:/home/steam/steamcmd
    environment:
      - TZ=${TZ}
      - PUID=${PUID}
      - PGID=${PGID}
      - UPDATE_ON_START=${UPDATE_ON_START}
      - STEAM_USER=${STEAM_USER}
      - STEAM_PASSWORD=${STEAM_PASSWORD}
      - SERVER_NAME=${SERVER_NAME}
      - SERVER_PASSWORD=${SERVER_PASSWORD}
      - MAX_PLAYERS=${MAX_PLAYERS}
      - SECURE=${SECURE}
      - MOTD=${MOTD}
      - SERVER_LANG=${SERVER_LANG}
      - NPC_STREAM=${NPC_STREAM}
      - FORCE_PRIORITY=${FORCE_PRIORITY}
      - DISABLE_ANNOUNCEMENT_BOX=${DISABLE_ANNOUNCEMENT_BOX}
      - ANNOUNCEMENT_BOX_RANGE=${ANNOUNCEMENT_BOX_RANGE}
      - SAVE_NAME=${SAVE_NAME}
      - WORLD_SEED=${WORLD_SEED}
      - WORLD_SIZE=${WORLD_SIZE}
      - WORLD_DIFFICULTY=${WORLD_DIFFICULTY}
    ports:
      - "${HOST_PORT}:7777/tcp"

And a .env file next to it (never commit this file — it contains your Steam password):

# --- System ---
TZ=Europe/Paris
PUID=1000
PGID=1000

# --- Steam account (mandatory — see "Why do I need a Steam account?") ---
STEAM_USER=your_steam_login
# If your password contains a literal "$", double it as "$$", otherwise
# Docker Compose tries to interpret it as a variable (e.g. "pa$$word" for
# "pa$word").
STEAM_PASSWORD=your_steam_password

# --- Updates ---
# true  = check/download Terraria updates every container start
# false = keep whatever version is already installed (faster restart,
#         no repeated Steam Guard prompts)
UPDATE_ON_START=false

# --- Server ---
SERVER_NAME=My_Terraria_Server
SERVER_PASSWORD=changeme
MAX_PLAYERS=8
SECURE=true
MOTD=
SERVER_LANG=en-US
NPC_STREAM=
FORCE_PRIORITY=
DISABLE_ANNOUNCEMENT_BOX=false
ANNOUNCEMENT_BOX_RANGE=

# --- World (only used the FIRST time the world file is created — see
#     "World settings only apply once" below) ---
SAVE_NAME=world1
WORLD_SEED=
WORLD_SIZE=2
WORLD_DIFFICULTY=0

# --- Networking ---
# Host port to expose. Change only the left side if you want a different
# public port; the container always listens on 7777 internally.
HOST_PORT=7777

⁠3. Start the server

docker compose up -d
docker compose logs -f

First start will take a few minutes: SteamCMD needs to download the game files. Watch the logs — if STEAM_USER has Steam Guard's mobile authenticator enabled, confirm the login request in the Steam Mobile app (check the "Confirmations" tab, not just push notifications) or the approval email.

⁠Environment variables reference

⁠Why do I need a Steam account?

Terraria is a paid game. SteamCMD's anonymous login (which works for many free-to-play dedicated servers) is not authorized for Terraria — you must log in with an account that genuinely owns it on Steam. Using a throwaway/shared account you don't want your primary credentials on is common practice; just make sure it actually owns a copy of Terraria.

Also note: Steam lists AppID 105610 ("Terraria - Dedicated Server") as the "official" dedicated server listing, but it has been broken since the Terraria 1.4 update — Re-Logic confirmed this on the Steam forums. This image uses AppID 105600 (the base game) instead, whose Linux depot also contains TerrariaServer.bin.x86_64.

⁠World settings only apply once

SAVE_NAME, WORLD_SEED, WORLD_SIZE and WORLD_DIFFICULTY only affect the world the first time it's created. Changing them later has no effect on an existing world — delete the corresponding .wld file inside your mounted saves folder if you want to regenerate a new world with different settings.

⁠Troubleshooting

• Restart loop + no Steam Guard prompt reaching you: if login keeps failing while restart: unless-stopped is set, the container will retry in a loop and spam Steam Guard confirmation requests — Steam eventually stops sending them (anti-abuse protection). If this happens:
  1. docker compose down immediately to stop the spam.
  2. Check the Confirmations tab in the Steam Mobile app (not just push notifications — a request can sit there without notifying you).
  3. Check the Steam account's email for a security alert to confirm.
  4. Wait 30–60 minutes before retrying.
  5. While debugging, temporarily set restart: "no" in docker-compose.yml to limit retries to a single attempt instead of looping forever, then switch back to unless-stopped once login succeeds.
• WARN ... variable is not set or a broken container name: your STEAM_PASSWORD likely contains a $ that isn't doubled to $$ in .env.
• "No subscription" / "no license" errors: double-check you're using AppID 105600 and that STEAM_USER genuinely owns Terraria — see above.

⁠Rebuilding after changes

• Changed start_server.sh or Dockerfile? Rebuild the image: docker build -t ludix0/terraria:latest .
• Changed only docker-compose.yml or .env? Just docker compose up -d — no rebuild needed.

⁠Français

Un serveur dédié Terraria auto-hébergé, tournant dans Docker, basé sur cm2network/steamcmd:root. Le conteneur télécharge et exécute le binaire Linux officiel TerrariaServer.bin.x86_64 via SteamCMD, puis le lance avec un utilisateur non-root.

⁠Prérequis

• Docker Engine + le plugin Docker Compose (docker compose, pas l'ancien docker-compose).
• Un compte Steam qui possède réellement Terraria — voir Pourquoi un compte Steam ?⁠ ci-dessous.
• Le port 7777/TCP accessible depuis là où vos joueurs se connectent (ouvrez-le et redirigez-le vers la machine qui fait tourner Docker si besoin). Terraria n'a besoin que du TCP — pas d'UDP.

⁠1. Récupérer les fichiers

Option A — récupérer l'image déjà construite sur Docker Hub (le plus rapide) :

docker pull ludix0/terraria:latest

Créez ensuite vous-même les deux fichiers ci-dessous (docker-compose.yml et .env) dans un dossier vide, puis passez directement à l'étape 3.

Option B — cloner depuis GitHub et construire l'image soi-même :

git clone <URL-de-ce-dépôt>
cd terraria
docker build -t ludix0/terraria:latest .

⁠2. Configurer — docker-compose.yml et .env

Créez un docker-compose.yml de ce type :

services:
  terraria:
    image: ludix0/terraria:latest
    container_name: terraria
    restart: unless-stopped
    volumes:
      - ./filesServer:/home/steam/terraria_server
      - ./saves:/home/steam/terraria_saves
      - ./steamcmd:/home/steam/steamcmd
    environment:
      - TZ=${TZ}
      - PUID=${PUID}
      - PGID=${PGID}
      - UPDATE_ON_START=${UPDATE_ON_START}
      - STEAM_USER=${STEAM_USER}
      - STEAM_PASSWORD=${STEAM_PASSWORD}
      - SERVER_NAME=${SERVER_NAME}
      - SERVER_PASSWORD=${SERVER_PASSWORD}
      - MAX_PLAYERS=${MAX_PLAYERS}
      - SECURE=${SECURE}
      - MOTD=${MOTD}
      - SERVER_LANG=${SERVER_LANG}
      - NPC_STREAM=${NPC_STREAM}
      - FORCE_PRIORITY=${FORCE_PRIORITY}
      - DISABLE_ANNOUNCEMENT_BOX=${DISABLE_ANNOUNCEMENT_BOX}
      - ANNOUNCEMENT_BOX_RANGE=${ANNOUNCEMENT_BOX_RANGE}
      - SAVE_NAME=${SAVE_NAME}
      - WORLD_SEED=${WORLD_SEED}
      - WORLD_SIZE=${WORLD_SIZE}
      - WORLD_DIFFICULTY=${WORLD_DIFFICULTY}
    ports:
      - "${HOST_PORT}:7777/tcp"

Et un fichier .env à côté (ne le mettez jamais dans un dépôt Git — il contient votre mot de passe Steam) :

# --- Système ---
TZ=Europe/Paris
PUID=1000
PGID=1000

# --- Compte Steam (obligatoire — voir "Pourquoi un compte Steam ?") ---
STEAM_USER=votre_identifiant_steam
# Si votre mot de passe contient un "$", doublez-le en "$$", sinon Docker
# Compose essaie de l'interpréter comme une variable (ex: "pa$$word" pour
# "pa$word").
STEAM_PASSWORD=votre_mot_de_passe_steam

# --- Mises à jour ---
# true  = vérifie/télécharge les mises à jour Terraria à chaque démarrage
# false = garde la version déjà installée (redémarrage plus rapide, pas de
#         demande Steam Guard répétée)
UPDATE_ON_START=false

# --- Serveur ---
SERVER_NAME=Mon_Serveur_Terraria
SERVER_PASSWORD=changeme
MAX_PLAYERS=8
SECURE=true
MOTD=
SERVER_LANG=fr-FR
NPC_STREAM=
FORCE_PRIORITY=
DISABLE_ANNOUNCEMENT_BOX=false
ANNOUNCEMENT_BOX_RANGE=

# --- Monde (utilisé UNIQUEMENT à la première création du monde — voir
#     "Les réglages du monde ne s'appliquent qu'une fois" ci-dessous) ---
SAVE_NAME=world1
WORLD_SEED=
WORLD_SIZE=2
WORLD_DIFFICULTY=0

# --- Réseau ---
# Port hôte exposé. Ne changez que le côté gauche pour un port public
# différent ; le conteneur écoute toujours en interne sur 7777.
HOST_PORT=7777

⁠3. Démarrer le serveur

docker compose up -d
docker compose logs -f

Le premier démarrage prend quelques minutes : SteamCMD doit télécharger les fichiers du jeu. Surveillez les logs — si STEAM_USER a l'authentification mobile Steam Guard activée, confirmez la demande de connexion dans l'application Steam Mobile (onglet "Confirmations", pas seulement les notifications push) ou via l'email de validation.

⁠Référence des variables d'environnement

⁠Pourquoi un compte Steam ?

Terraria est un jeu payant. La connexion anonyme de SteamCMD (qui fonctionne pour beaucoup de serveurs dédiés de jeux free-to-play) n'est pas autorisée pour Terraria — il faut se connecter avec un compte qui le possède réellement sur Steam. Utiliser un compte secondaire/dédié (plutôt que votre compte principal) est une pratique courante ; assurez-vous simplement qu'il possède bien une copie de Terraria.

Autre point important : Steam liste l'AppID 105610 ("Terraria - Dedicated Server") comme la fiche "officielle" du serveur dédié, mais elle est cassée depuis la mise à jour Terraria 1.4 — confirmé par Re-Logic sur les forums Steam. Cette image utilise donc l'AppID 105600 (le jeu de base), dont le dépôt Linux contient aussi TerrariaServer.bin.x86_64.

⁠Les réglages du monde ne s'appliquent qu'une fois

SAVE_NAME, WORLD_SEED, WORLD_SIZE et WORLD_DIFFICULTY n'affectent le monde qu'à sa toute première création. Les changer ensuite n'a aucun effet sur un monde déjà créé — supprimez le fichier .wld correspondant dans votre dossier saves monté si vous voulez régénérer un nouveau monde avec de nouveaux réglages.

⁠Problèmes fréquents

• Boucle de redémarrage sans que la demande Steam Guard vous parvienne : si la connexion échoue en boucle alors que restart: unless-stopped est actif, le conteneur va spammer des demandes de confirmation Steam Guard — Steam finit par arrêter de les envoyer (protection anti-abus). Si ça arrive :
  1. docker compose down immédiatement pour arrêter le spam.
  2. Vérifiez l'onglet Confirmations de l'application Steam Mobile (pas seulement les notifications push — une demande peut y être sans avoir notifié).
  3. Vérifiez les emails du compte Steam pour une alerte de sécurité à confirmer.
  4. Attendez 30 à 60 minutes avant de retenter.
  5. Pendant le débogage, passez temporairement restart: "no" dans docker-compose.yml pour limiter les tentatives à un seul essai au lieu d'une boucle infinie, puis remettez unless-stopped une fois la connexion validée.
• WARN ... variable is not set ou un nom de conteneur cassé : votre STEAM_PASSWORD contient probablement un $ non doublé en $$ dans .env.
• Erreurs "No subscription" / "no license" : vérifiez que vous utilisez bien l'AppID 105600 et que STEAM_USER possède réellement Terraria — voir ci-dessus.

⁠Reconstruire après une modification

• Vous avez modifié start_server.sh ou Dockerfile ? Reconstruisez l'image : docker build -t ludix0/terraria:latest .
• Vous avez modifié seulement docker-compose.yml ou .env ? Un simple docker compose up -d suffit — pas besoin de reconstruire.