The Programmer's Guide to Hosting a Minecraft Server

Docker

This writeup is not intended to serve as an introduction to Docker, so if you haven’t used it before I suggest you follow some tutorials before using it for Minecraft. The key thing to understand is that a Docker container is a great way to manage a Minecraft server.

This task is made easy by the docker-minecraft-server image by itzg. There’s also a version for Bedrock edition, but I have no experience with that. I like to use Docker Compose to specify my containers, since it makes version control incredibly simple. All you need to do it create a file called compose.yaml and specify your configuration options. Here’s the template I use:

services:
  mc:
    image: itzg/minecraft-server
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    restart: "always"
    environment:
      EULA: "TRUE"
      MEMORY: "6144M"
      TZ: "America/New_York"
      VERSION: "1.21.8"
      DIFFICULTY: "2"
      SPAWN_PROTECTION: "0"
      OPS: |-
        <your-player-name>

    volumes:
      - ./data:/data

Here’s a quick explanation of some of the settings:

• tty and stdin_open: Settings for input and output through the terminal. Don’t change these unless you know what you are doing.

• ports: A range of ports exposed by the container. 25565 is the default port for Minecraft, so again, I wouldn’t change this.

  • If you have something that requires extra ports, like a server map or voice-chat mod, you will need to add those ports here.
  • DO NOT add the RCON port here, unless you want people to be able to access your server console from outside networks.

• restart: Specifies the restart policy of the server. The value always means that the server will automatically be started again after it is stopped. Thus, you can restart the server by simply invoking the /stop command.

• The environment settings correspond to Minecraft server settings, and should be self explanatory. You don’t actually have to provide a game version, since the Docker image will use the latest by default. However, I don’t like it when my server updates without my explicit permission, so I always specify a game version.

  • See the documentation for a full list of server.properties settings that can be specified here.

• volumes: A mapping from directories on your computer to virtual directories in the Docker container. This can be a little tricky if you have’t used Docker before. In my compose file, I state that the data directory (Make sure to create this directory in the same parent directory as compose.yaml) should be used to house all of the server files. This directory is then mounted to the container as a volume called /data.

I highly recommend this configurator tool from setupmc.com. It gives you a GUI for generating your compose file, and has explanations for many of the settings.

Note: Docker requires root access by default. I recommend adding your user to the Docker group so you don’t have to sudo the following commands.

Once you’ve set up your compose file, starting your server is simple. Make sure you navigate to the directory containing compose.yaml. Then run the following command, and you should see an output that looks similar.

$ docker compose up -d
[+] Running 2/2
 ✔ Network server_default  Created       0.1s
 ✔ Container server-mc-1   Started       2.0s

The -d flag starts the container detached. To attach the container, and access the server console, you can run:

$ docker compose attach <container-name>

<container-name> is the string shown when you created your container, e.g. server-mc-1 in the example above.
This command should plop you into the container terminal. To detach the container again, press ctrl-p then ctrl-q.

As discussed above, stopping the server application will just cause it to restart again. To terminate the entire Docker container, run the following command:

$ docker compose down

When the server is down, it is safe to modify the files in the data directory. Doing this while the server is running can cause files to become corrupted and should be avoided.

I like to put these three commands into short shell scripts for convenience, so that I can just run ./start.sh etc., instead of remembering the Docker command syntax each time.

The overall structure of the server directory should look something like this:

server
├── data
│   └── <server files>
├── docker-compose.yaml
├── attach.sh
├── start.sh
└── stop.sh

Another benefit of Docker is that it handles shutdown commands gracefully. For example, if you wanted to reboot your system, you would want to make sure that the Minecraft server saves the world and stops itself before terminating, or else your data could become corrupted. Docker will automatically propagate the shutdown command, eliminating the headache.

While Docker can become incredibly complex for larger projects, it makes running a Minecraft server incredibly simple.

Modded Servers

I rarely run vanilla Minecraft servers nowadays. Even when I make a server which does not require any client-side mods, I usually use server-side Fabric mods for optimization and other utilities. The traditional way to manage server mods involves manually downloading .jar files, placing them into the mods directory, and praying. If anything needs to be updated or has a version conflict (you might be familiar with the pain of installing large custom modpacks), it can take hours to find appropriate files and revert to a stable version.

Surely there is a better way to do this.

$ packwiz init
Modpack name [Modpack]: server-pack
Author: Emery
Version [1.0.0]:
Minecraft version [1.21.10]: 1.21.8
Mod loader [quilt]: fabric
Fabric loader version [0.18.1]:
index.toml created!
Refreshing index... 0 % [------------------------------------------] done
pack.toml created!

$ packwiz modrinth install ferrite-core
Project "FerriteCore" successfully added!

$ packwiz modrinth install lithium
Project "Lithium" successfully added!

$ packwiz modrinth install krypton
Project "Krypton" successfully added!

packwiz
├── index.toml
├── mods
│   ├── ferrite-core.pw.toml
│   ├── krypton.pw.toml
│   └── lithium.pw.toml
└── pack.toml

services:
  mc:
    image: itzg/minecraft-server
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    restart: "always"
    environment:
      EULA: "TRUE"
      TYPE: "Fabric"
      MEMORY: "6144M"
      TZ: "America/New_York"
      VERSION: "1.21.8"
      DIFFICULTY: "2"
      SPAWN_PROTECTION: "0"
      OPS: |-
        <your-player-name>
      PACKWIZ_URL: "/packwiz/pack.toml"

    volumes:
      - ./data:/data
      - ./packwiz:/packwiz

├── data
│   └── <server-files>
├── docker-compose.yaml
├── packwiz
│   ├── index.toml
│   ├── mods
│   │   └── <modpack-files>
│   └── pack.toml
├── attach.sh
├── start.sh
└── stop.sh

Git

One of the many benefits of using Docker Compose and packwiz is that the server files can be generated deterministically from a set of text files. And the best part of working exclusively with text files is that they can be tracked seamlessly with Git.

In fact, I have a single Git repo containing all of my servers. It has proven useful for version control, as I have the ability to revert to earlier versions in the frequent case that I mess up my modpacks. Another benefit is portability: setting up a server on a different machine is as simple as pulling from GitHub.

docker-minecraft-server is very powerful, and can supply pretty much all of the configuration items you would normally specify in server.properties.

The one major caveat is that you should not attempt to track your server files themselves with Git, since the data files can be many gigabytes in size. As such, you should blacklist the data directory in your .gitignore:

**/data/

Do not use Git for world backups.

If you want to back up your worlds, you should create copies of the data directory locally or cloud machine, or preferably, use one of the many server-backup mods/plugins/tools that exist on the Internet.

Scripting

One of the nice things about running a server on your own machine is that you can interact with it programmatically. Minecraft servers support a protocol called RCON, which lets you remotely execute commands. We can use this protocol in external scripts for fun and profit.

$ docker exec <container-name> rcon-cli <command> ...

$ docker exec clms-mc-1 rcon-cli list
There are 0 of a max of 20 players online:

$ docker exec clms-mc-1 rcon-cli say Hello World!
# No output, but players in-game will see `[rcon] Hello World!`

# restart.py
#!/usr/bin/env python3

import argparse
from subprocess import run
import time


def rcon(cmd: str) -> str:
    """Tries to run a command through the server's RCON interface."""
    args = cmd.split()
    output = run([*args], capture_output=True).stdout
    return str(output)


def online_players(server_name: str) -> int:
    """Get the number of online players, or -1 if there is an error."""
    try:
        player_listing = rcon(f"docker exec {server_name} rcon-cli list")
        return int(player_listing.split()[2])

    except Exception:
        return -1


def warn_server(server_name: str, delay_s: int) -> None:
    """Warn the server about an impending reboot."""
    minutes, seconds = divmod(delay_s, 60)

    if minutes:
        delay_time = f"{minutes} minute(s)"
        if seconds:
            delay_time = f"{delay_time} and {seconds} second(s)"
        else:
            delay_time = "5 seconds"
    else:
        if seconds:
            delay_time = f"{seconds} second(s)"
        else:
            delay_time = "5 seconds"
    rcon(
        f"docker exec {server_name} rcon-cli say Server will automatically reboot in {delay_time}."
    )


def warn_and_wait(server_name: str, delay_s: int) -> None:
    """Warn players, then wait the appropriate duration."""
    if delay_s <= 60:
        # If the delay is a minute or less, only warn once.
        warn_server(server_name, delay_s)
        time.sleep(delay_s)

    else:
        # Otherwise, warn again at the 1 minute mark.
        warn_server(server_name, delay_s)
        time.sleep(delay_s - 60)
        warn_server(server_name, 60)
        time.sleep(60)


def shut_down(server_name: str) -> None:
    """Shuts down the server."""
    rcon(f"docker exec {server_name} rcon-cli say Rebooting server...")
    time.sleep(5)  # Add a slight delay just in case anybody is still online.
    rcon(f"docker exec {server_name} rcon-cli stop")


def main(server_name: str, delay_s: int) -> None:
    num_online = online_players(server_name)
    if num_online == -1:
        return  # If the server isn't running or there is some other error, do nothing.

    if num_online > 0:
        warn_and_wait(server_name, delay_s)
    shut_down(server_name)


if __name__ == "__main__":
    ap = argparse.ArgumentParser(
        prog="Minecraft Server Auto-Restarter",
        description="A script that shuts down a Minecraft server in a Docker container after a delay.",
    )
    ap.add_argument(
        "-n", "--name", type=str, required=True, help="The name of the Docker container"
    )

    ap.add_argument(
        "-d",
        "--delay",
        type=int,
        required=False,
        default=300,
        help="The delay in restarting the server in seconds after the initial announcement. Do not make this more than 59m59s.",
    )
    args = ap.parse_args()
    main(args.name, args.delay)

chmod +x restart.py

crontab -e

0 2 * * * ~/path/to/restart.py

Conclusion

These are some of the tools I use in maintaining Minecraft servers. Keep in mind that people keep developing new ones, so it’s a good idea to periodically check forums to see what people are using. Furthermore, there are a lot of ways to run a Minecraft server, and different approaches might be suited to each one.

Overall, the important takeaways from this writeup are:

• You can use developer tools to great effect in hosting Minecraft servers.

• Things that are good practice in software development, such as containerization and dependency management, are useful elsewhere.

• Be careful not to expose your Minecraft server to external threats. Use a whitelist. Keep online mode enabled. And do not expose any more ports than you absolutely need.

  • I am not responsible if you get pwned.