passivelemon/terraria-docker repository overview

⁠terraria-docker⁠

Unofficial Docker container for a Terraria dedicated server. Supports vanilla and modded through tModLoader.

⁠Quick setup summary (Vanilla)

1. Setup a directory for you server files. Can be something like /opt/TerrariaServer/(Linux) or C:\TerrariaServer\(Windows).
2. Run the container: (Make sure to modify any values that you need)

• docker run -d --name terraria -p 7777:7777/tcp -v /opt/TerrariaServer/:/opt/terraria/config/ -e WORLD=myworld passivelemon/terraria-docker:terraria-latest

1. Setup server access.

⁠Quick setup summary (Modded)

1. Setup a directory for you server files. Can be something like /opt/TerrariaServer/(Linux) or C:\TerrariaServer\(Windows).
2. Add your modpack to the previous directory in the sub-directory ModPacks/ (See step 3 further down)
3. Run the container: (Make sure to modify any values that you need)

• docker run -d --name tmodloader1.4 -p 7777:7777/tcp -v /opt/TerrariaServer/:/opt/terraria/config/ -e MODPACK=<modpack name> -e WORLD=myworld passivelemon/terraria-docker:tmodloader-latest

1. Setup server access.

⁠1. Setting up main server files

Depending on your host, find a suitable place to store your server files. Make sure it is empty, safe, and accessible. For example: On Windows, something like C:\TerrariaServer\ or a Linux equivalent like /opt/TerrariaServer/.

In <config_dir>, make one directory called Worlds, spelled exactly as show, and Modpacks if you are using tModLoader. This location is also where your serverconfig.txt will be stored if you want to use your own. Details on this are in step 4.

⁠2. Server environment variables

For every variable you want the server to use, add that variable to your docker run or compose with -e <variable>=<value>. If not set, they will use their default value.

By default, modded servers will not successfully run because they need a defined modpack.

Server configuration details on the Terraria Wiki⁠.

⁠Container variables

⁠Server variables

⁠Journey Mode

All Journey Mode variables have the same options. The default is 2. 0 for no-one, 1 for host only, 2 for everyone.

⁠3. Modpacks

If you are not using tModLoader, then skip this step.

Ideally, you shouldn't include any client side only mods in the modpack folder for the server. Client side mods only affect the client (player) meaning they add zero new functionality to the game. Includes things like different textures, shaders, RPC, etc. Nothing bad should happen if you do but it's just best practice. Mods are included in the modpack folder so they do not need to be obtained manually.

1. In tModLoader on a client, enable any mods that you want to play with.
2. Go to the mod pack section.
3. "Save Enabled as New Mod Pack"
4. "Open Mod Pack folder"
5. Copy the folder of the modpack you want to use in the server and paste that into <config_dir>/ModPacks/

Make sure the modpack has an enabled.json with the mods you want or else the server will not start.

⁠4. Worlds

If you want to continue on an existing world, follow this step. Otherwise, just skip it. The server will generate a new world automatically.

If you provide a world file and correctly set the WORLDNAME variable, it will use the existing world. If using tModLoader, make sure this world is always loaded with the same modpack or you may encounter world corruption.

1. Find your world file:

• Vanilla worlds can be found at C:\Users\<user>\Documents\My Games\Terraria\Worlds\ or the Linux equivalent, usually /home/<user>/.local/share/Terraria/Worlds/.
• Modded worlds can be found at C:\Users\<user>\Documents\My Games\Terraria\tModLoader\Worlds\ or the Linux equivalent, usually /home/<user>/.local/share/Terraria/tModLoader/Worlds/.

1. Copy the files of the world of your choice to <config_dir>/Worlds/. The world files look like .wld and, if using tModLoader, .twld.

⁠5. Server config

If you want to use your own server config, follow this step. Otherwise, just skip it. The server will generate a config automatically based on your provided environment variables.

The root of the terraria server files in the container is /opt/terraria/server/ and user items in <config_dir> are mounted at /opt/terraria/config/

1. Set SERVERCONFIG to 1.
2. Put the serverconfig.txt into <config_dir>.

Server configuration details on the Terraria Wiki⁠.

⁠6. Docker container

Though stable are likely fine, it is recommended to pin the server to a specific version to avoid potential save corruption.

Terraria versions at releases⁠. tModLoader versions at tModLoader⁠ (Do not include the v prefix).

⁠Docker run

docker run -d --name <container name> -p 7777:7777 -v <config_dir>:/opt/terraria/config/ passivelemon/terraria-docker:terraria-latest

⁠Docker Compose

services:
  terraria-docker:
    image: passivelemon/terraria-docker:terraria-latest
    container_name: terraria-docker
    ports:
      - 7777:7777
    volumes:
      - <config_dir>:/opt/terraria/config/

⁠Examples

⁠Docker run

docker run -d --name terraria -p 7777:7777/tcp -v /opt/terrariaServer/:/opt/terraria/config/ -e WORLD=myworld passivelemon/terraria-docker:terraria-latest

⁠Docker compose

services:
  terraria-docker:
    image: passivelemon/terraria-docker:terraria-latest
    container_name: terraria-docker
    ports:
      - 7777:7777
    volumes:
      - /opt/terrariaServer/:/opt/terraria/config/
    environment:
      WORLDNAME: "myworld"

⁠Healthcheck

If you have a service that depends on the health state of the container, you can add a healthcheck as such:

services:
  terraria-docker:
    # ...
    healthcheck:
      test: "nc -vz 127.0.0.1 7777 || exit 1" # Change 7777 to your internal server port if needed
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

Note that this can inhibit server hibernation when no players are present.

⁠7. Reference

Your config directory should look something like:

<config_dir>\       # This gets mounted to /opt/terraria/config/ in the container.
  Logs\             # This is optional. Make sure to mount it if you want it to be populated.
  Worlds\           # Default folder needed by the server.
  ModPacks\         # Modpack directory if using tModLoader.
  serverconfig.txt  # config file needed by the server (Only if you want to use your own).

⁠8. Access

Theres a few ways around this:

• Playing completely over LAN. If your server and players are on the same network, then you can use the local IP of the server host.

• Playing over a VPN like Tailscale, ZeroTier, or other. You can then follow the same logic as LAN.

• Playing remotely through a domain or public IP. See below.

Unless you plan to play completely locally or over a VPN, you will need to port forward for players outside of your network to access the server. The general idea of port forwarding is when a client sends a request to the server (with a specific port), a properly set up port forward will allow the request to go through and to the specified host. Terraria uses 7777 by default but you can change this in your config file.

If you do not have access to your network infrastructure, you will need to resort to either playing over LAN or a VPN.

1. Head to your router web interface by typing your gateway IP into your router. It might be 192.168.1.1, 172.1.0.1 or something else. This will vary depending on how your network is setup.

2. Find the port forwarding section. Your router management software is probably going to be different but theres a good chance that its just called "port forwarding" or under a "NAT" tab or something of the likes. EX: For PFsense, it is under NAT and is called Port Forwarding. Your inputs may also look a little different. Please consult your software manufactuerers manual for guidance if you do not know what you are doing.

3. Set the external or incoming port. This is the port that players will type when they try to join your server.

4. Set the internal or outgoing port. This is the port that will be used by Docker. This is the first part of the -p 7777:7777. The second part is the container port. This is what you put into your server config (7777 by default).

5. Set your destination IP. This will be the IP of your server/host. There are many ways to find it. Go to your terminal: Windows is ipconfig. Most Linux distros have ip a or ifconfig or a similar command. Look for your interface, whether it is wifi or wired, and find your IPV4 address. It might look like 192.168.1.XXX or 172.1.0.XXX. Again, will probably be different.

• If you do not have a static local IP address for your host, it might eventually change. If this happens, your port forwarding will no longer work. Research how to set up a static IP on your router.

1. Find your public IP address. You can go to whatismyip⁠ or elsewhere and use the IPv4 address that it returns. If have a domain, you probably don't need these instructions.

• NOTE: While this won't pin point your location, it can give users some geographical information.

You will also need a port. If you didn't change the defaults, it will just be 7777. If you did change from defaults, it will be whatever port you set as your external port in your router.

More info on the Fandom⁠ and at whatismyip.com/port-forwarding/⁠.

⁠9. Other

⁠Command injection

You can run the command docker exec <container name> inject "<command>" to inject a command directly into the server. An example: docker exec terraria inject "say Hello from the server!"

More info on the Terraria Wiki⁠.

⁠Caching dotnet

If you would like for the container to not attempt to download dotnet every boot, then add a volume flag to your container to /opt/terraria/server/dotnet/. Ex: -v <config_dir>/dotnet_cache.

Just beware that there could be versioning issues in the future if the target dotnet runtime version is updated, hence why the dotnet runtime is not saved by default.

⁠10. The end

Assuming you did everything correctly, you should have a functional server that will automatically load the world upon start.

Have fun!

⁠Credits

rfvgyhn⁠ for the server injection functionality.