finallf/terraria repository overview

Features⁠  •  Requirements⁠  •  Quick Setup⁠  •  Environment Variables⁠  •  Dynamic Inventory⁠  •  Volumes⁠  •  Security⁠

⁠🖥️ About the project

⁠This is a high-performance image for Terraria servers. Designed with a focus on automation, data security, detailed monitoring, and is completely rootless.

⁠🪶 Features

⁠Internal Architecture (Without Supervisor):

• ✅ Native and lightweight execution, optimized for high-performance Linux and container environments, completely rootless.

⁠Robust Logging System:

• ✅ Full log capture (STDOUT/STDERR) with highly accurate timestamps, allowing for complete auditing from boot to shutdown.

⁠Configuration Management:

• ✅ It uses jq for manipulating JSON files, ensuring that your settings (such as the initial inventory) can be changed without risk of file corruption.

⁠Interactivity via Named Pipe:

• ✅ It allows commands to be sent to the server console externally and securely, facilitating integration with scripts and web interfaces.

⁠Graceful Shutdown:

• ✅ A signal capture system (SIGTERM) that ensures the server saves the world's progress before being terminated by Docker.

⁠❓ Why use this image?

• If you manage servers in any professional Docker environment, you know that visibility is everything.

• This image was built for administrators who need reliable logs and dynamic configurations via environment variables, without sacrificing the simplicity of docker-compose.

⁠⚒️ Minimum Requirements

⁠🧰 Quick Setup

If you want to test the container, use the shell command:

docker run --rm -di --terraria finallf/terraria:latest

The recommended way to run your server is using Docker Compose.

 1 - Create a compose.yml file and adapt the volume paths to your environment, similar to this:

services:
  terraria:
    image: finallf/terraria:latest
    container_name: terraria
    stdin_open: true
    tty: false
    environment:
      - SERVER_PASSWORD=yourpassword123
      - WORLD_NAME=My World Terraria
    volumes:
      # Map these folders to persist your data on the host.
      - ./terraria/config:/tshock/config
      - ./terraria/logs:/tshock/logs
      - ./terraria/crashes:/tshock/crashes
      - ./terraria/plugins:/tshock/plugins
      - ./terraria/worlds:/tshock/worlds
    ports:
      - "7777:7777" # Game Port
      - "7878:7878" # REST API Port (Optional)
    restart: unless-stopped

 These are the minimum required settings.
 For more refined settings, see the Environment Variables⁠ section for more information.

 2 - Make sure that the folders on the host have the correct permissions for the UID, the container runs by default with UID 1000.

 3 - To begin, run the following command in the terminal, in the directory containing the compose.yml file:

docker compose up -d

Once your Docker container is running, open your Terraria client and connect using the host's IP address and the default port 7777.

If this is the first time running the container, it may take a while due to world creation.

 4 - You can also monitor the startup:

tail -f ./tshock/logs/container_init.log

⁠⚙️ Environment Variables

You can configure the server behavior using the variables below in your compose.yml file or via the -e flag in docker run:

⁠🎒 Dynamic Inventory ( STARTINGINVENTORY )

The Dynamic Inventory system allows you to define which items new players will receive when they first join the server, without needing to edit files manually. The script processes this information atomically on boot using jq.

🔹 Option 1: Basic Kit (Quick Mode)
   - If you set the variable to true, the server automatically injects a default starter kit:
   (99 Glowsticks, 99 Ironskin Potions, 1 Aglet, 1 Ice Mirror, 1 Gravedigger's Shovel).

environment:
  - STARTINGINVENTORY=true

🔹 Option 2: Customized Kit (Advanced Mode)
   - To define specific items, use the compact string format:
   ID, PREFIX, QUANTITY separated by a colon ( : ).

   Syntax: netID,prefix,stack:netID,prefix,stack:...

   Practical Example:
   For players to start with a Platinum Axe (ID: 3482), 10 Torches (ID: 8), and 5 Lesser Healing Potion (ID: 28):

environment:
  - STARTINGINVENTORY=3482,0,1:8,0,10:28,0,5

🔹 Option 3: Removing an item
   - You can also remove any item from the list:
   Using 'remove:ID'

   Syntax: remove:netID

   Practical Example:
   We will remove the Platinum Axe (ID: 3482)

environment:
  - STARTINGINVENTORY=remove:3482

⁠💾 Persistence Structure (Volumes)

To ensure your server maintains its progress after reboots or image updates, it's necessary to map the 5 main volumes. Below, we detail the content and purpose of each:

• 📁 /tshock/config
  • Contents: JSON configuration files and SQLite database (config.json, sscconfig.json, tshock.sqlite).
  • Purpose: This is the "brain" of the server rules. This volume is where our boot script performs dynamic changes. Note: The sscconfig.json file resides here and is where the initial inventory is managed.

• 📁 /tshock/logs ( optional )
  • Contents: The container_init.log file and native TShock logs.
  • Purpose: Auditing and diagnostics. This volume allows you to monitor what happened during boot ( such as the injection of items by jq ) and view server errors without needing to access the Docker console.

• 📁 /tshock/crashes ( optional - legacy )
  • Contents: Memory dump files (crash dumps) from an unexpected crash.
  • Purpose: This is only necessary if you are a TShock plugin developer or are debugging deep crashes (segfaults/memory crashes) and need to organize the .dmp files into a specific network folder or volume.

• 📁 /tshock/plugins ( optional )
  • Contents: Additional plugins and extensions for TShock.
  • Purpose: Customization. By mapping this volume, you can add new features to the server (such as saving systems or area protection) simply by copying the files to the folder on your host, without needing to rebuild the Docker image.

• 📁 /tshock/worlds
  • Contents: Map files ( .wld ) and automatic backup folders.
  • Purpose: Stores the "body" of your server. This is where all construction, mining, and terrain modifications are saved. Without this volume, the world will be reset on every reboot.

⁠🔐 Security and Permissions (Rootless Architecture)

To ensure the highest level of security, this image was built following the Rootless standard. This means that the TShock server and all internal scripts do not run as administrator (root) within the container.

This prevents game vulnerabilities from compromising your physical server (host), but requires correct configuration of the permissions for the mapped folders in your compose.yml file.

🔹 How does a static UID/GID work
By default, the container's internal process runs with a static User ID (e.g., UID 1000) and belongs to the Root Group (GID 0).

• Why Group 0? Using GID 0 is a recommended practice (adopted by platforms like Red Hat OpenShift) that allows for flexibility. The container does not require that the user who owns the folder on the host be exactly 1000, as long as the folder's group allows read and write access.

🔹 How to prepare your folders on the Host
Before starting the container for the first time, you need to ensure that the directory where the volumes will be saved allows writing.

• Method 1: Adjust the owner in the container (Recommended)
  If you want to be strict, change the UID in your compose.yml file to match the UID of your host (replace 1000 with your UID):

services:
  terraria:
    user: 1000:0

• Method 2: Adjust the owner on the host (no flexibility)
  Alternatively, you can change the folder owner on your host to match the container UID:

sudo chown -R 1000:1000 ./terraria

• Method 3: Group 0 (More flexible)
  If you don't want to change the user who owns your folder, simply grant write permission to Group 0:

sudo chgrp -R 0 ./terraria
sudo chmod -R g+rwX ./terraria

Whichever method you choose, the container will be able to write logs, worlds, and sscconfig.json without permission conflicts, keeping Rootless security intact.

⁠🛡️ Monitoring and Logs

This image was designed following the philosophy of total observability. Every step of the initialization and every command sent to the server is recorded with chronological precision.

📁 Log Locations
To persist logs outside the container, map a volume in your compose.yml file:

volumes:
  - /path/to/host/logs:/tshock/logs

The main file will be container_init.log, where you will find the complete trace of:

• Injection of items and boot scripts.
• Creation and status of the Named Pipe communication system.
• Real-time output from the TShock console (STDOUT/STDERR).

🕒 Precision Timestamps
Unlike standard logs, our system prefixes each line with a customizable timestamp:

[2026-04-05 14:30:05] [INFO] Items successfully added to starting inventory.

This allows you to cross-reference error information with events from your file system or network on the host.

📟 Console-based interactivity (Named Pipe)
Since the server runs in the background to allow monitoring, you don't use docker attach.
To send commands (such as kick, ban, or save), use the built-in Named Pipe:

Example of a command via the terminal:

docker exec -i [container_name] sh -c 'echo "say Hello Terrarians!" > /tmp/terraria_input'

🛑 Graceful Shutdown
When you send a docker stop command, the container captures the interrupt signal and automatically executes a save script.
This ensures that the world's progress is written to disk before the process is terminated, preventing the dreaded "roll-back" of items.

⁠☕ Support the Project / Apoie o Projeto

If this project has helped you in any way, consider buying me a coffee! Your donation helps keep the updates and documentation current.

🇧🇷 Se este projeto te ajudou de alguma forma, considere me pagar um café! Sua doação ajuda a manter as atualizações e a documentação.

🌎 GitHub Sponsors		PayPal
You can support me through GitHub Sponsors.	🇧🇷 Escaneie o QR Code:	Click or scan the QR code:

🇧🇷 Ou utilize a Chave Pix (Copia e Cola):

25d1d528-df10-4005-bb28-2acf89706243

⁠💪 How to contribute to the project

⁠🛠️ Technologies

The following tools were used in the construction of the project:

⁠🧑‍💻 Collaborators:

💜 Thank you to everyone who contributed to the improvement of this project 😊

Finallf ⁠

semantic-release-bot ⁠

⁠🧙‍♂️ Author:

⁠📝 License: