terraria-server-manager/README.md

terraria-server-manager

Run any number of vanilla Terraria and tModLoader dedicated servers on one Linux host. Each server is its own systemd service, and they're all managed with the terractl command.

sudo terractl new calamity tmodloader
sudo terractl mods calamity add ~/tmod-export
sudo terractl enable calamity --now
sudo terractl attach calamity

Features

• Many servers, one host. Each instance is terraria@<name>.service, with its own directory, port, world and mods.
• Vanilla and tModLoader side by side, chosen per instance.
• No manual installs. terractl fetch downloads official Terraria and tModLoader server zips (or drop them into /var/lib/terraria/dist yourself); they're unpacked on demand, and each instance can be pinned to a specific version. terractl upgrade checks a new zip, backs up the worlds and switches version in one step.
• Safe shutdowns. Stopping a server saves the world first.
• A live console. terractl attach shows the server's output and lets you type commands into it; terractl watch just shows the output.
• Mod management. terractl mods installs, enables and removes mods, with correct file ownership.
• Tab completion for commands, instance names, mods and console commands.
• Export and import. Pack an instance into one .tar.gz for backups or moving to another machine, and import it anywhere, with paths, ports and ownership adjusted.
• Scheduled backups. terractl backup enable <name> backs an instance up daily (or on any schedule) with a systemd timer, saving the world first and keeping the newest 14.
• Self-check. terractl doctor checks the whole setup, explains what's wrong with the command to fix it, and --fix fixes what it safely can.
• Manage other hosts. Run any command on another host with terractl --host nas ..., and copy or move instances between hosts with terractl copy and terractl move, like LXD/Incus remotes. Hosts opt in by running the terractld daemon; access is per computer, over pinned TLS.
• Hardened. Servers run as an unprivileged terraria user and can only write to their own data.
• Access for moderators. Members of the terraria group can start, stop and restart servers, use the console and read the servers' own logs, without sudo and without seeing the rest of the system's logs.
• Helper for Windows. A PowerShell script exports your enabled tModLoader mods for the server.

Requirements

• Debian 12+ or Ubuntu 22.04+ (other systemd-based distributions should work with make install)
• unzip, systemd; for tModLoader, also curl and ICU (libicu)
• python3 and openssl, for managing other hosts

Install

From the apt repository, which also brings updates with sudo apt upgrade:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key \
  -o /etc/apt/keyrings/terraria-server-manager.asc
echo "deb [signed-by=/etc/apt/keyrings/terraria-server-manager.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" |
  sudo tee /etc/apt/sources.list.d/terraria-server-manager.list
sudo apt update
sudo apt install terraria-server-manager

Or download the .deb from the releases page, then:

sudo apt install ./terraria-server-manager_<version>_all.deb

Or install from source, without a package:

sudo make install

Documentation

See docs/guide.md. It covers installation, creating instances, the console, configuration, mods, versions and upgrades, permissions and troubleshooting. Installed systems also have it at /usr/share/doc/terraria-server-manager/README.md.

Repository layout

bin/terractl               The command-line tool
systemd/                   terraria@.service and terraria@.socket
completions/bash/          Bash completion for terractl
config/                    /etc/default settings, sysusers.d and tmpfiles.d entries
packaging/deb/             Debian package metadata and install/remove scripts
docs/guide.md              Full documentation
tools/windows/             export-tmod-mods.ps1 for exporting mods from Windows
VERSION                    Current version, used by the build
Makefile                   make check | deb | install | uninstall | clean

Building

make check     # bash -n on all scripts, plus shellcheck if installed
make deb       # build/terraria-server-manager_<version>_all.deb

To release, update VERSION and CHANGELOG.md, commit, and push a matching tag:

git tag v$(cat VERSION) && git push origin v$(cat VERSION)

The release workflow (.gitea/workflows/release.yaml, Gitea Actions) then builds the .deb, publishes it as a release with that version's changelog section as the notes, and adds it to the apt repository. It needs a runner with the ubuntu-latest label. To build a package by hand instead, run make deb.

Disclaimer

This is an unofficial community tool. It is not affiliated with or endorsed by Re-Logic or the tModLoader team. It does not include any Terraria or tModLoader software; you supply the official server downloads.