How to use this image

Starting an instance

By default, this starts up a Minecraft 1.8.8 server instance. If you wish tostart a different Minecraft server version, you need to set theMINECRAFT_VERSION variable to the appropriate version.

You must set the DEFAULT_OP variable on startup. This should be yourMinecraft username. The container will fail to run if this is not set.

When starting a Minecraft server, you must agree to the terms stated inMinecraft's EULA. This can be done by setting the MINECRAFT_EULA variableto true. Without this, the server will not run.

This image exposes the standard minecraft port (25565).

When starting a container for the first time, it will check for the existence ofthe Minecraft Server jar file, and will download from Mojang when necessary. Asmuch as I want to package the Minecraft server jar in this image (to also saveon time and the hassle of an extra step), I cannot due to the Minecraft EULA.

It is highly preferred to start the container with -it. This is needed inorder to allow executing console commands via docker exec. This also allowsthe Minecraft server to safely shutdown when stopping the container viadocker stop. See the Scripting section for more details.

Commands

The image uses an entrypoint script called minecraft, which allows you toexecute preset commands. Should you attempt to execute an unrecognized command,it will treat it as a regular shell command.

The commands are as follows:

run - This runs the Minecraft server, and is the default command used by thecontainer. This command can accept additional parameters (if minecraftsupports other options apart from nogui). Useful whencreating a new container via docker create or docker run

permissions - This updates the permissions of all related files andfolders. Useful when manually editing a file.

console - This executes a console command. This allows system administratorsto perform complex tasks via scripts. This feature is off by default. See theScripting section for more details and examples.

permissions - update file and folder permissions while a container is running

docker exec minecraft-instance minecraft permissions

Scripting

Unlike other Minecraft Docker Images, this image provides a way to executeconsole commands without attaching to the docker container. It lets systemadministrators perform much more complex tasks, such as managing the dockercontainer from another docker container (e.g. deploying using Jenkins).

For those who are used to running docker attach inside a screen or tmuxsession for scripting, this is going to be heaven.

This feature can be enabled by pasing the -it parameter to docker create ordocker run, which enables STDIN and TTY. This runs the Minecraft server insidea tmux session. This also enables safe shutdown mode when the container isstopped.

Once enabled, you may now execute console commands like so:

docker exec minecraft-instance minecraft console say hello everybody!

Some warnings when using this feature:

DO NOT USE -it ON docker exec! For some reason, it crashesthe tmux session that drives this feature.

Be careful when attaching to the console via docker attach. You areattaching to a tmux session running on the foreground with the footerdisabled. Do not try to detach from the tmux session using CTRL-b d,otherwise this will stop the container. To detach from the container, useCTRL-p CTRL-q, which is the standard escape sequence for docker attach.

Here is an example on how to notify players that the server will be shutdownafter 60 seconds:

#!/bin/bash
docker exec minecraft-instance minecraft console say We will be shutting down the server in 60s!
docker exec minecraft-instance minecraft console say Stop whatever you are doing!
sleep 60
docker exec minecraft-instance minecraft console say We will be back in 1 hour!
sleep 5
# The container will send the stop console command to the server for you, to
# ensure that the server is shutdown safely.
#
# Of course you can run this manually like so:
#
# docker exec minecraft-instance minecraft console stop
#
# But this will restart the container if the restart policy is set to always.
docker stop -t 60 minecraft-instance

Data volumes

Previously, this image has one data volume: /var/lib/minecraft. This volumeused to contain world data. If you are using an older version of this dockerimage, you will need to move the contents of this folder to /opt/minecraft.

The decision to change this was due to the way Vanilla Minecraft works.

Unlike Spigot, which is capable of changing the location of the world data,Vanilla Minecraft (and by extension, Modded Minecraft), does not play nice withthis. Even though they technically support it, mods and other sysads expect theworld data to reside inside the main Minecraft folder.

And when you try to support both vanilla and modded servers, it becomes morecomplex. Vanilla servers will have 3 world folders (e.g. world,world_nether, world_the_end), while modded servers will only have world.

To keep things simple, I've removed the data volume definition. It is now up tothe user to declare the appropriate data volume either at runtime, or whenextending the image.

If you're running a Vanilla server, you may opt to declare /opt/minecraft as adata volume. This not only simplifies data management, it allows you to takeadvantage of the ONBUILD trigger that comes with this image. See theONBUILD Trigger section for details.

Environment Variables

The image uses environment variables to configure the JVM settings and theserver.properties.

MINECRAFT_EULA

MINECRAFT_EULA is required when starting creating a new container. You need toagree to Minecraft's EULA before you can start the Minecraft server.

DEFAULT_OP

DEFAULT_OP is required when starting creating a new container.

MINECRAFT_OPTS

You may adjust the JVM settings via the MINECRAFT_OPTS variable.

Environment variables for server.properties

On startup, it will check the existence of server.properties. If it doesnot exist, one will be created for you. You may override the defaults bysetting the appropriate environment variable.

Each entry in the server.properties file can be changed by passing theappropriate variable. To make it easier to remember and configure, the variablerepresentation of each entry is in uppercase, and uses underscore insteadof dash.

The server port cannot be changed. This has to be remapped when starting aninstance.

For reference, here is the list of environment variables for server.propertiesthat you can set:

GENERATOR_SETTINGS

OP_PERMISSION_LEVEL

ALLOW_NETHER

LEVEL_NAME

ENABLE_QUERY

ALLOW_FLIGHT

ANNOUNCE_PLAYER_ACHIEVEMENTS

LEVEL_TYPE

ENABLE_RCON

FORCE_GAMEMODE

LEVEL_SEED

SERVER_IP

MAX_BUILD_HEIGHT

SPAWN_NPCS

WHITE_LIST

SPAWN_ANIMALS

SNOOPER_ENABLED

ONLINE_MODE

RESOURCE_PACK

PVP

DIFFICULTY

ENABLE_COMMAND_BLOCK

PLAYER_IDLE_TIMEOUT

GAMEMODE

MAX_PLAYERS

SPAWN_MONSTERS

VIEW_DISTANCE

GENERATE_STRUCTURES

MOTD

Extending this image

This image is meant to be extended for packaging custom maps, modpacks, andconfigurations as Docker images. For server owners, this is the best way toroll out configuration changes and updates to your servers.

If you wish to do so, here are some of the things you will need to know:

ONBUILD Trigger

This Docker image contains one ONBUILD trigger, which copies any local filesto /usr/src/minecraft.

When a container is started for the first time, the contents of this folder iscopied to /opt/minecraft via rsync, except for anything that starts withworld.

World Templates

This Docker image supports the use of world templates, which is useful forpackaging custom maps. World templates should always start with world, whichhas been a standard Minecraft convention (e.g. world, world_nether,world_the_end). Copy your world templates to /usr/src/minecraft via theONBUILD trigger. During startup, it will check if /opt/minecraft/world isempty. If so, it will create a copy of the world template on this folder.

Environment Variables in Dockerfile

MINECRAFT_HOME (Read-only!)

To make your life simple, this variable points to where Minecraft is installed.This points to /opt/minecraft. Useful for creating scripts when packagingmodpacks.

DO NOT OVERRIDE THIS. CHANGES TO THIS VARIABLE ARE IGNORED!

MINECRAFT_VERSION

Modpacks will require a specific Minecraft version in order to work. This canbe done setting the MINECRAFT_VERSION in your Dockerfile.

MINECRAFT_STARTUP_JAR

When packaging a modpack, you will need to start the server using a differentjar file. To specify the startup jar, set the MINECRAFT_STARTUP_JAR variablein your Dockerfile.

MINECRAFT_OPTS

Some modpacks have their own recommended JVM settings. You can include themvia the MINECRAFT_OPTS variable in your Dockerfile.