Terraria Server 🍕

A Docker-based Terraria server setup that lets you quickly deploy and manage a Terraria multiplayer server. This repository provides a fully containerized Terraria server that's easy to configure and run on any system that supports Docker. It uses the official Terraria server application, wrapped in a Docker container for consistency and portability.

The server:

Runs Terraria version 1.4.4.9 (PC/Vanilla)
Supports customizable world generation
Allows adjustable difficulty settings
Includes password protection options
Preserves world data between container restarts

Mobile support is now available! Run a Terraria Mobile Edition server using the new mobile profile. See server/mobile/README.md for details.

TShock support is now available! Run a TShock-enabled Terraria server using the new tshock profile. See the TShock Wiki for advanced configuration, plugins, and moderation tools.

Requirements

Docker: Installation guide
Docker Compose: Usually bundled with Docker Desktop
Minimum 2GB RAM and 1GB storage space
Open port 7777/TCP on your network (for external connections)

How to Run

Prebuilt Images

You can run the server using prebuilt images from GitHub Container Registry (GHCR) without cloning this repository.

See Vanilla server arguments
See Mobile server arguments

Vanilla (PC) server:

docker run -d \
  --name vanilla-server \
  -p 7777:7777 \
  -e WORLD_NAME=world \
  -e WORLD_SIZE=2 \
  -e DIFFICULTY=0 \
  -e MAX_PLAYERS=8 \
  -v vanilla-worlds:/terraria-server/worlds \
  ghcr.io/meshi-team/terraria-server-vanilla:latest

Mobile server:

docker run -d \
  --name mobile-server \
  -p 7777:7777/udp \
  -p 7777:7777/tcp \
  -e WORLD_NAME=world \
  -e WORLD_SIZE=1 \
  -e DIFFICULTY=0 \
  -e MAX_PLAYERS=8 \
  -v mobile-worlds:/terraria-server/worlds \
  ghcr.io/meshi-team/terraria-server-mobile:latest

Or use the prebuilt images in your docker-compose.yml by replacing the build: section with the appropriate image: line (see comments in the provided compose file).

From Source

To build and run the server from source, follow these steps:

Clone this repository:

git clone https://github.com/meshi-team/terraria-server.git
cd terraria-server

Start the server with a specific profile:

# Start the vanilla Terraria server (PC)
docker compose --profile vanilla up -d

# Start the Terraria Mobile server
docker compose --profile mobile up -d

# Start the TShock server
docker compose --profile tshock up -d

View server logs:
```
docker compose logs -f
```
Stop the server:
```
docker compose down
```

Server Profiles

Currently available profiles:

vanilla: The official Terraria server (PC) - version | documentation
mobile: Terraria Mobile Edition server - version | documentation
tshock: TShock server with advanced moderation tools and plugin support

TShock Server

The TShock server provides advanced moderation, REST API, and plugin support for Terraria.
To use TShock, start the server with the tshock profile:

docker compose --profile tshock up -d

TShock data, configuration, and plugins are stored in the ./tshock, ./worlds, and ./plugins directories (mounted as volumes).
The REST API is available on port 7878 by default.

For more information, configuration options, and plugin management, see the TShock Wiki.

Configuration

Edit the docker-compose.yml file to customize your server:

environment:
  - WORLD_NAME=world # Name of your Terraria world
  - WORLD_SIZE=2 # World size: 1=small, 2=medium, 3=large
  - MAX_PLAYERS=8 # Maximum number of players allowed
  - PASSWORD= # Server password (leave blank for no password)
  - DIFFICULTY=0 # 0=normal, 1=expert, 2=master, 3=journey
  - SEED= # World seed (leave blank for random)

After changing configuration, restart the server:

docker compose down
docker compose up -d

Environment Variables

The server can be customized using the following environment variables:

Init Settings

Variable	Default Value	Description
SERVER_FOLDER	/terraria-server	Main server directory
SERVER_BIN	TerrariaServer	Server binary name
CONFIG_FOLDER	/terraria-server/config	Configuration directory
CONFIG_FILE	server-config.txt	Server configuration filename
CONFIG_TEMPLATE	config-template.cfg	Template configuration file
SCRIPTS_FOLDER	/terraria-server/scripts	Scripts directory
LOGS_FOLDER	/terraria-server/logs	Logs directory
LOGS_FILE	terraria-server.log	Log filename

World Settings

Variable	Default Value	Description
WORLD_NAME	world	World name
WORLD_SIZE	1	World size (1: small, 2: medium, 3: large)
WORLD_ROLLBACKS_TO_KEEP	2	Number of world backups to maintain
WORLD_SEED	""	World generation seed

Game Settings

Variable	Default Value	Description
DIFFICULTY	0	Game difficulty (0: classic, 1: expert, 2: master, 3: journey)
MAX_PLAYERS	8	Maximum number of players allowed
PORT	7777	Server port
PASSWORD		Server password
MOTD	"Welcome to my server!"	Message of the day
BANLIST_FILE	/terraria-server/banlist.txt	Path to banlist file
SECURE	1	Enable secure mode (1: on, 0: off)
LANGUAGE	en-US	Server language
UPNP	1	Enable UPnP (1: on, 0: off)
NPC_STREAM	60	NPC stream range
PRIORITY	1	Process priority
SLOW_LIQUIDS	1	Enable slow liquids (1: on, 0: off)
ENABLE_STEAM	0	Enable Steam integration (1: on, 0: off)

Journey Mode Power Permissions

Permission values: 0: Locked for everyone, 1: Can only be changed by host, 2: Can be changed by everyone

Variable	Default Value
JOURNEY_PERMISSION_TIME_SET_FROZEN	1
JOURNEY_PERMISSION_TIME_SET_DAWN	1
JOURNEY_PERMISSION_TIME_SET_NOON	1
JOURNEY_PERMISSION_TIME_SET_DUSK	1
JOURNEY_PERMISSION_TIME_SET_MIDNIGHT	1
JOURNEY_PERMISSION_GODMODE	1
JOURNEY_PERMISSION_WIND_SET_STRENGTH	1
JOURNEY_PERMISSION_RAIN_SET_STRENGTH	1
JOURNEY_PERMISSION_TIME_SET_SPEED	1
JOURNEY_PERMISSION_RAIN_SET_FROZEN	1
JOURNEY_PERMISSION_WIND_SET_FROZEN	1
JOURNEY_PERMISSION_INCREASE_PLACEMENT_RANGE	1
JOURNEY_PERMISSION_SET_DIFFICULTY	1
JOURNEY_PERMISSION_BIOMESPREAD_SET_FROZEN	1
JOURNEY_PERMISSION_SET_SPAWN_RATE	1

Connecting to Your Server

Open Terraria on your device
Select "Multiplayer"
Select "Join via IP"
Enter your server's IP address (or localhost if running locally)
Enter port 7777 (default)
Enter password (if configured)

Common Issues

Can't connect remotely: Check firewall settings and port forwarding
Server crashes: Check logs with docker-compose logs -f
World data persistence: Data is stored in Docker volumes, don't remove them if you want to keep your world

Server Management

Accessing the Console

Connect to the running server console using:

docker attach terraria

To detach without stopping the server: press Ctrl+P followed by Ctrl+Q

Common Commands

help - List all commands
exit - Save and shutdown the server
playing - Show connected players
kick <player> - Remove a player
ban <player> - Ban a player
save - Force world save

For a complete list of commands, refer to the Official Terraria Wiki.

For Developers

Development Environment Setup

Using VS Code DevContainer (Recommended)

Install VS Code and Docker
Install the VS Code "Remote - Containers" extension
Clone this repository
Open the repository in VS Code
When prompted, click "Reopen in Container" or run the "Remote-Containers: Reopen in Container" command

The DevContainer includes all necessary development tools:

Various linters and formatters (yamllint, shellcheck, hadolint, etc.)
Git configuration
Shell utilities

Project Structure

.
├── docker-compose.yml
├── LICENSE
├── package.json
├── package-lock.json
├── README.md
└── server
    ├── <server-type>
    │   ├── config
    │   │   └── config-template.cfg
    │   ├── Dockerfile
    │   ├── README.md
    │   ├── scripts
    │   │   ├── entrypoint.sh
    │   │   ├── generate-server-config.sh
    │   │   ├── load-env.sh
    │   │   └── start-server.sh
    │   └── terraria-version

Where <server-type> is either vanilla or mobile.

Contributing

Fork the repository
Create a feature branch with a descriptive name
Make your changes following the code style guidelines
Run linting and formatting checks before committing
Submit a pull request with a conventional commit title:
- Format: <type>(<scope>): <subject>
- Valid types: feat, fix, perf, refactor, revert, chore, ci, docs
Ensure all CI checks pass

Workflow Tools

Linting:

npm run lint            # Run ESLint
npm run lint-fix        # Fix auto-fixable ESLint issues

Formatting:

npm run format          # Format code with Prettier

si, pongan boff.

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.config		.config
.devcontainer		.devcontainer
.github		.github
server		server
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Terraria Server 🍕

Table of contents

Requirements

How to Run

Prebuilt Images

From Source

Server Profiles

TShock Server

Configuration

Environment Variables

Init Settings

World Settings

Game Settings

Journey Mode Power Permissions

Connecting to Your Server

Common Issues

Server Management

Accessing the Console

Common Commands

For Developers

Development Environment Setup

Using VS Code DevContainer (Recommended)

Project Structure

Contributing

Workflow Tools

About

Uh oh!

Releases 3

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Terraria Server 🍕

Table of contents

Requirements

How to Run

Prebuilt Images

From Source

Server Profiles

TShock Server

Configuration

Environment Variables

Init Settings

World Settings

Game Settings

Journey Mode Power Permissions

Connecting to Your Server

Common Issues

Server Management

Accessing the Console

Common Commands

For Developers

Development Environment Setup

Using VS Code DevContainer (Recommended)

Project Structure

Contributing

Workflow Tools

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages