How to Self-Host a Terraria Server with Docker

What Is a Terraria Dedicated Server?

Terraria is a 2D sandbox game with over 44 million copies sold. A dedicated server lets multiple players explore, build, and fight bosses in the same world simultaneously without requiring the host player to be online. Self-hosting gives you control over world settings, player count, mods (via TShock), and persistence — the world is always available, not just when the host is playing.

Updated February 2026: Verified with latest Docker images and configurations.

Two Docker options exist: Vanilla (official server software) and TShock (community mod framework with permissions, plugins, and anti-cheat). Most multiplayer groups use TShock for its management features.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 512 MB of free RAM (minimum)
• 1 GB of free disk space
• Port 7777/TCP open on your firewall
• A domain name (optional — players connect by IP)

Docker Compose Configuration

Vanilla Server

Create a project directory:

mkdir -p /opt/terraria && cd /opt/terraria

Create a docker-compose.yml file:

services:
  terraria:
    image: ghcr.io/beardedio/terraria:vanilla-1.4.5.6
    restart: unless-stopped
    tty: true            # Required — server fails without TTY
    stdin_open: true     # Required — enables interactive console
    ports:
      - "7777:7777/tcp"  # Game server
    volumes:
      - terraria-data:/config  # World files and server config
    environment:
      world: /config/Worlds/MyWorld.wld  # World file to load

volumes:
  terraria-data:

TShock Server (Recommended for Multiplayer)

services:
  terraria:
    image: ghcr.io/beardedio/terraria:tshock-5.2.4
    restart: unless-stopped
    tty: true            # Required — server fails without TTY
    stdin_open: true     # Required — enables interactive console
    ports:
      - "7777:7777/tcp"  # Game server
    volumes:
      - terraria-data:/config                    # World files and config
      - terraria-plugins:/tshock/ServerPlugins   # TShock plugins (optional)
    environment:
      world: /config/Worlds/MyWorld.wld  # World file to load

volumes:
  terraria-data:
  terraria-plugins:

First Run — World Generation

The first time you start the server, it needs to generate a world. Run interactively:

docker compose run --rm terraria

The server will prompt you for:

1. World size (1=Small, 2=Medium, 3=Large)
2. World difficulty (1=Normal, 2=Expert, 3=Master, 4=Journey)
3. World name
4. World seed (optional — leave blank for random)

After generation completes, stop the server (Ctrl+C) and note the world filename. Update the world environment variable in docker-compose.yml to match:

environment:
  world: /config/Worlds/YourWorldName.wld

Now start the server normally:

docker compose up -d

Initial Setup

1. Open Terraria on your gaming PC
2. Select “Multiplayer” → “Join via IP”
3. Enter your server’s IP address and port 7777
4. If using TShock, you’ll see “This server is running TShock” on connect

TShock Admin Setup

On first TShock start, the server generates a setup code in the logs:

docker compose logs terraria | grep "setup-code"

Connect to the server as a player and enter in chat:

/setup <your-setup-code>

Then set yourself as the owner:

/user add YourName YourPassword owner

From now on, authenticate with:

/login YourPassword

Key TShock Commands

Command	Description
/login <password>	Authenticate as registered user
/ban add <player>	Ban a player
/kick <player>	Kick a player
/give <item> <player>	Give items
/time set day	Change time of day
/godmode	Toggle god mode
/tp <player>	Teleport to player
/world save	Force world save

Configuration

Server Settings

For vanilla servers, edit serverconfig.txt in the config volume:

docker compose exec terraria cat /config/serverconfig.txt

For TShock, server settings are in /config/tshock/config.json:

Setting	Default	Description
MaxSlots	8	Maximum player slots
ServerPassword	(empty)	Password to join
SpawnProtection	true	Protect spawn area from building
SpawnProtectionRadius	10	Tiles of protection around spawn
AntiCheat	true	TShock anti-cheat system
EnableWhitelist	false	Only allow whitelisted players

World Size Performance

Size	Dimensions	RAM Usage	Disk Space	Players Supported
Small	4200×1200	~200 MB	~5 MB	1-4
Medium	6400×1800	~350 MB	~15 MB	4-8
Large	8400×2400	~500 MB	~30 MB	8-16

TShock Plugins

Install plugins by placing .dll files in the plugins volume:

# Download a plugin
wget -O plugin.dll https://example.com/plugin.dll

# Copy to the plugins volume
docker cp plugin.dll terraria:/tshock/ServerPlugins/

# Restart to load
docker compose restart terraria

Popular TShock plugins include WorldEdit, InfiniteChests, and WorldRegeneration.

Reverse Proxy

Terraria uses TCP for game traffic on port 7777. Standard HTTP reverse proxies don’t apply — players connect directly to your IP.

Firewall rules (UFW):

sudo ufw allow 7777/tcp

If behind a router, forward port 7777/TCP to your server’s local IP.

Backup

What to Back Up

Data	Location	Importance
World files	terraria-data volume (/config/Worlds/)	Critical
TShock config	terraria-data volume (/config/tshock/)	Important
Player data	terraria-data volume (/config/tshock/tshock.sqlite)	Important (TShock)
Plugins	terraria-plugins volume	Low (re-downloadable)

Manual Backup

# Save the world first (via RCON or in-game command)
docker compose exec terraria /bin/bash -c "echo 'save' > /proc/1/fd/0"

# Create backup
docker compose stop terraria
tar czf terraria-backup-$(date +%Y%m%d).tar.gz -C /var/lib/docker/volumes/ terraria-data
docker compose start terraria

For automated backups, see Backup Strategy.

Troubleshooting

Server Crashes on Start — “Null Reference Exception”

Symptom: Server exits immediately with NullReferenceException in logs.

Fix: Ensure tty: true and stdin_open: true are set in your Docker Compose file. The Terraria server requires a TTY to operate — without it, the process crashes immediately.

World Not Loading — “World file not found”

Symptom: Error message about missing world file.

Fix:

1. Verify the world file exists: docker compose exec terraria ls /config/Worlds/
2. Check the world environment variable matches the exact filename including .wld extension
3. File path must be absolute (start with /config/)
4. If no world exists, run the interactive world generation step first

Players Can’t Connect — Timeout

Symptom: Players get “Connection timeout” when trying to join.

Fix:

1. Verify port 7777/TCP is open: sudo ufw status
2. Check the server is running: docker compose logs terraria | tail -20
3. Test port accessibility: nc -zv your-server-ip 7777
4. If behind NAT, verify port forwarding on your router
5. Some ISPs block common game ports — try changing to a different port

TShock Plugins Not Loading

Symptom: Installed plugin doesn’t appear in /plugins list.

Fix:

1. Verify the .dll file is in the correct directory: docker compose exec terraria ls /tshock/ServerPlugins/
2. Check TShock version compatibility — plugins compiled for older TShock versions may not load
3. Check logs for plugin load errors: docker compose logs terraria | grep -i plugin
4. Restart the server after adding plugins

Resource Requirements

Resource	Minimum	Recommended
RAM	256 MB	512 MB - 1 GB
CPU	1 core	2 cores
Disk	500 MB	1-2 GB
Network	Stable connection	Low latency preferred

Terraria servers are remarkably lightweight compared to modern game servers. A $5/month VPS handles 8-16 players comfortably.

Verdict

Terraria dedicated servers are one of the easiest game servers to self-host. Low resource requirements (256 MB RAM minimum), simple configuration, and excellent community Docker images make it a great first game server project. TShock adds essential multiplayer management features — permissions, anti-cheat, and plugins — that vanilla servers lack.

Self-hosting a Terraria server costs $5-10/month on a VPS versus $10-15/month for hosted solutions like Shockbyte or Nodecraft. The real advantage isn’t cost savings — it’s full control over world settings, mods, and player management without vendor restrictions.

Frequently Asked Questions

What’s the difference between Vanilla and TShock?

Vanilla is the official Terraria server software with no modifications — it supports basic multiplayer but has no permissions, anti-cheat, or plugin system. TShock is a community mod framework that adds user groups, permissions, anti-cheat, server-side characters, and a plugin system. Most multiplayer groups use TShock for its management features.

Can I run a Terraria server on a Raspberry Pi?

Yes, but with limitations. Terraria servers are x86 only in the official Docker images, so you’d need to use QEMU emulation on ARM, which adds overhead. A Raspberry Pi 4 with 4 GB RAM can handle a small world with 2-4 players, but performance degrades with larger worlds. A cheap x86 VPS is a better option for reliable performance.

How do I update the server to a new Terraria version?

Update the image tag in your docker-compose.yml to match the new game version, then run docker compose pull && docker compose up -d. Back up your world files first. TShock updates may lag behind vanilla Terraria releases by days or weeks — check the TShock GitHub releases for compatibility.

Can players join from different platforms (PC, mobile, console)?

No. Terraria dedicated servers only support PC (Steam) players. Console and mobile versions use different netcode and cannot connect to PC dedicated servers. All players must be on the same PC version of Terraria to connect.

How do I run multiple worlds on the same server?

Run separate Docker containers for each world, each on a different port. Change the host port mapping (e.g., 7778:7777 for a second world) and set a different world environment variable pointing to each world file. Players connect to the specific port for the world they want to join.

Does the server need to match the client version exactly?

Yes. The Terraria server version must match the client version exactly. If Terraria updates on Steam, your server needs the matching image tag. Pin your Docker image version and coordinate updates with your players to avoid connection issues.

Related

• Best Self-Hosted Game Servers
• How to Self-Host a Minecraft Server
• How to Self-Host a Palworld Server
• How to Self-Host a Valheim Server
• Self-Hosted Alternatives to Game Server Hosting
• Docker Compose Basics
• Backup Strategy