Notes »

Minecraft server with Podman

I’m running a Minecraft server in my LAN for the family to play in the same world.

It should be OK running it from the jar file, but I decided to use podman because:

  • It adds security and “peace of mind” because I’m running it in my personal desktop PC.
  • I wanted to try podman as root-less alternative to Docker.
  • You may need to use root to set permissions and edit some of the files because they aren’t owned by your user (e.g. use sudo if you have it configured).

Install in Debian

sudo apt install podman crun slirp4netns uidmap fuse-overlayfs

Notes:

  • Apparently you can also use the runc runtime.
  • Both slirp4netns and uidmap are “recommended packages”, but they are needed in this case.
  • fuse-overlayfs is also a “recommended package”, but I have encountered issues with the default vfs storage driver (e.g. stuck on Storing signatures).

Note: if you started using vfs –like I did–, you may need to stop your containers and, keeping safe your volumes, remove ~/.local/share/containers/storage before installing fuse-overlayfs. Then pull the images again and it should be using overlay. It is unfortunate that podman uses the best available driver by default, independently of your existing storage, and they aren’t compatible.

Configure registries

By default podman on Debian doesn’t come with any registries configured.

mkdir -p $HOME/.config/containers
echo 'unqualified-search-registries=["docker.io", "quay.io"]' > $HOME/.config/containers/registries.conf

From Podman page in Debian’s wiki; although having only docker.io is probably enough.

Start script

I don’t want to run the container all the time, so this is convenient to start it when needed.

#!/bin/bash
# start the minecraft server

NAME=minecraft-server
VOLUME=$HOME/pods/minecraft/data

podman ps | grep $NAME && exit

TAG=java21-alpine

podman run -d -it --rm -p 25565:25565 -e EULA=TRUE \
    --name $NAME \
    -v $VOLUME:/data itzg/minecraft-server:$TAG

This expects some directories in place, run:

mkdir -p $HOME/pods/minecraft/data

Tip: save as start script in $HOME/pods/minecraft/.

Setup the server

  1. Start the container and check the logs until it has finished.
  2. Stop it and edit server.properties changing anything you want.
  3. Start the server again.

I’m using itzg/minecraft-server, and these are the docs.

The clients can connect using the IP of the machine running the server (in my case, in my LAN).

Server cheat-sheet

  • Start the server: see start script
  • Stop the server: podman stop minecraft-server
  • Check the logs: podman logs -f minecraft-server

Useful console commands

Disable raids:

podman exec minecraft-server rcon-cli '/gamerule disableRaids true'

Spawn entities:

podman exec minecraft-server rcon-cli '/summon minecraft:chicken x y z'

(get the x y z coordinates from a player by pressing F3 on their client; ensure the player is in an appropriate place!)

How to convert a local save

We started playing on a new world and I was sharing it from my Minecraft instance to the LAN, but then that means I must be running my Minecraft when the rest of the family wants to play in our shared world (and the night → sleep cycle requires someone to control my character).

It is easy to convert the local save into a server world.

  1. Ensure the server is not running.
  2. Copy the world directory from $HOME/.minecraft/saves/ to $HOME/pods/minecraft/data.
  3. Change the ownership of the world directory (and subdirectories) to the user ID used by the container.

For example: if the user ID for the data directory is 100999, run:

chown -R 100999:100999 data/my-world-name
  1. Edit data/server.properties and add:
level-name=my-world-name

If your world name has spaces, you don’t need to use quotes, write it as-is.

Start the server and you are done!

Last updated Jan 9, 2025
MinecraftDevOps