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 systemctl enable --now terraria@calamity
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. Drop the official server zips into /var/lib/terraria/dist; they're unpacked on demand, and each instance can be pinned to a specific version.
• 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.
• 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.
• Hardened. Servers run as an unprivileged terraria user and can only write to their own data.
• 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)

Install

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, run make deb, and attach the .deb to the release.

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.