Running with a custom server JAR¶
If you would like to run a custom server JAR, set
-e TYPE=CUSTOM and pass the custom server
CUSTOM_SERVER. It can either be a URL or a container path to an existing JAR file.
If it is a URL, it will only be downloaded into the
/data directory if it wasn't already. As
such, if you need to upgrade or re-download the JAR, then you will need to stop the container,
remove the file from the container's
/data directory, and start again.
Force re-download of the server file¶
For VANILLA, FORGE, BUKKIT, SPIGOT, PAPER, CURSEFORGE, SPONGEVANILLA server types, set
$FORCE_REDOWNLOAD to some value (e.g. 'true) to force a re-download of the server file for
the particular server type. by adding a
-e FORCE_REDOWNLOAD=true to your command-line.
For example, with PaperSpigot, it would look something like this:
Running as alternate user/group ID¶
By default, the container will switch to user ID 1000 and group ID 1000;
however, you can override those values by setting
GID as environmental entries, during the
docker run command.
-e UID=1234 -e GID=1234
The container will also skip user switching if the
is passed to
Arguments that would usually be passed to the jar file (those which are written after the filename) can be passed via the
EXTRA_ARGS environment variable.
See Custom worlds directory path for an example.
Interactive and Color Console¶
If you would like to
docker attach to the Minecraft server console with color and interactive capabilities, then add
This feature doesn't work via rcon, so you will need to
docker attachto the container. Use the sequence Ctrl-P, Ctrl-Q to detach.
This will bypass graceful server shutdown handling when using
docker stop, so be sure the server console's
Make to enable stdin and tty with
tty: truewhen using docker compose.
This feature is incompatible with Autopause and cannot be set when
Server Shutdown Options¶
To allow time for players to finish what they're doing during a graceful server shutdown, set
STOP_SERVER_ANNOUNCE_DELAY to a number of seconds to delay after an announcement is posted by the server.
Increase stop grace period
The Docker stop grace period must be increased to a value longer than the announce delay. The value to use that is longer than announce delay will vary based upon the amount of time it takes for final world data saving. If the container exits with exit code 137, then that indicates a longer grace period is needed.
OpenJ9 Specific Options¶
The openj9 image tags include specific variables to simplify configuration:
-e TUNE_VIRTUALIZED=TRUE: enables the option to optimize for virtualized environments
-e TUNE_NURSERY_SIZES=TRUE: configures nursery sizes where the initial size is 50% of the
MAX_MEMORYand the max size is 80%.
Enabling rolling logs¶
By default the vanilla log file will grow without limit. The logger can be reconfigured to use a rolling log files strategy by using:
NOTE this will interfere with interactive/color consoles as described in the section above
You can configure the timezone to match yours by setting the
TZ environment variable:
docker run -d -it -e TZ=Europe/London -p 25565:25565 --name mc itzg/minecraft-server
/etc/timezone as readonly (not supported on Windows):
docker run -d -it -v /etc/timezone:/etc/timezone:ro -p 25565:25565 --name mc itzg/minecraft-server
You may configure the use of an HTTP/HTTPS proxy by passing the proxy's URL via the
environment variable. In the example compose file it references
a companion squid proxy by setting the equivalent of
Using "noconsole" option¶
Some older versions (pre-1.14) of Spigot required
--noconsole to be passed when detaching stdin, which can be done by setting
Explicitly disable GUI¶
Some older servers get confused and think that the GUI interface is enabled. You can explicitly
disable that by passing
When the container is signalled to stop, the Minecraft process wrapper will attempt to send a "stop" command via RCON or console and waits for the process to gracefully finish. By default it waits 60 seconds, but that duration can be configured by setting the environment variable
STOP_DURATION to the number of seconds.
If you are using a host-attached data directory, then you can have the image setup the Minecraft server files and stop prior to launching the server process by setting
Enable Flare Flags¶
To enable the JVM flags required to fully support the Flare profiling suite, set the following variable:
Flare is built-in to Pufferfish/Purpur, and is available in plugin form for other server types.
Enable support for optimized SIMD operations¶
To enable support for optimized SIMD operations, the JVM flag can be set with the following variable:
SIMD optimized operations are supported by Pufferfish and Purpur.
Enable timestamps in init logs¶
Before the container starts the Minecraft Server its output is prefixed with
[init], such as
To also include the timestamp with each log, set
LOG_TIMESTAMP to "true". The log output will then look like: