Supports any version of Minecraft; you just need a link to the server.jar
- tested on vanilla 1.21, more to come
- note: mod loaders (like Fabric, Forge, and Paper) are not officially supported, but they may still work
Server console access via RCON
- uses Tiiffi/mcrcon as a prepackaged RCON client
All server files stored in a Docker volume
Graceful shutdown handling (SIGTERM / SIGINT)

Usage

Requires Docker, Git, and a clone of this repository:

git clone https://gitea.jovan04.com/evan/minecraft-docker && cd minecraft-docker

Build the Image

docker build --pull -t minecraft_server .

Run with Docker Compose

In the same directory as docker-compose.yml (included in this repository):

docker compose up -d

(or docker-compose for older versions of Docker Compose)

First Startup

On first startup (when the data volume is empty):

Make sure to update the environment variables in the docker-compose.yml file
- MCRCON_PASS is the password to your server's RCON panel
- SERVER_JAR_DOWNLOAD_URL is a web URL of a server.jar file that the container will run to start your server
server.properties is created from a template
eula.txt is generated and automatically accepted
A default RCON configuration is written
server.jar is downloaded from a provided link

On subsequent startups, existing files are reused unchanged and environment variables are unused. To reset the server or create a new one, change the name in volumes: data: name: new_volume_name in the docker-compose.yml file.

Upgrading Java Version

Occasionally, Minecraft will update the Java version they compile their class files with. Because the Java runtime is pre-bundled with the Docker container, an update from Minecraft requires an update and rebuild of the Docker container.

You can tell this is required if there are errors like the following when trying to start the server:

minecraft_server  | Error: LinkageError occurred while loading main class net.minecraft.bundler.Main
minecraft_server  | 	java.lang.UnsupportedClassVersionError: net/minecraft/bundler/Main has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0
minecraft_server exited with code 1 (restarting)

To upgrade, change the base eclipse-temurin image's version to one supported by the latest Minecraft version. In ./Dockerfile:

# previously, eclipse-temurin:21
FROM eclipse-temurin:25

Then, rebuild the container and start as normal:

docker build --pull -t minecraft_server .
docker compose up -d

RCON Access

Minecraft implements the Remote Console (RCON) protocol, which allows server administrators to remotely execute commands. See more info here and here. RCON access is enabled automatically from inside the container only. Do not expose the RCON service to the internet directly!!! RCON is not encrypted, so exposing this service can give hackers direct access to your server's administrator console.

Log into the container:

docker exec -it minecraft_server bash

Use the provided wrapper script (located at /usr/bin/mcrcon). The script dynamically reads the password from /minecraft_data/server.properties.

Send a single command:

mcrcon list
mcrcon stop

For an interactive console (Ctrl-C or Ctrl-D to quit):

mcrcon

Use this the same as typing into the actual server console

Graceful Shutdown Behavior

When the container receives SIGTERM or SIGINT:

A 10-second warning message is broadcast to the server
All chunks are saved manually
A stop command is sent to the Minecraft server
The server shuts down normally
The container waits up to a configurable timeout before force-exiting, in case large worlds take a long time to save or the server hangs
- default 120s; configure this by changing the stop_grace_period time in docker-compose.yml

Configuration

All Minecraft configuration is done through server.properties. Make any necessary changes before building the image to the file in this repository, or manually edit the server.properties file in the Minecraft server's Docker volume. More info about Docker volumes can be found here. This container should work fine with a relative path in docker-compose.yml instead of a named volume.