Sign inSign up

spion06/minecraft-server

By spion06

•Updated over 3 years ago

fork of itzg/minecraft-server

Image
0

7.2K

spion06/minecraft-server repository overview

Docker Pulls Docker Stars GitHub Issues Discord Build and Publish

This docker image provides a Minecraft Server that will automatically download the latest stable version at startup. You can also run/upgrade to any specific version or the latest snapshot. See the Versions section below for more information.

To simply use the latest stable version, run

docker run -d -it -p 25565:25565 -e EULA=TRUE itzg/minecraft-server

where, in this case, the standard server port 25565, will be exposed on your host machine.

If you plan on running a server for a longer amount of time it is highly recommended using a management layer such as Docker Compose⁠ or Kubernetes⁠ to allow for incremental reconfiguration and image upgrades.

Be sure to always include -e EULA=TRUE in your commands and container definitions, as Mojang/Microsoft requires EULA acceptance.

By default, the container will download the latest version of the "vanilla" Minecraft: Java Edition server⁠ provided by Mojang. The VERSION⁠ and the TYPE⁠ can be configured to create many variations of desired Minecraft server.

TABLE OF CONTENTS

⁠Looking for a Bedrock Dedicated Server

For Minecraft clients running on consoles, mobile, or native Windows, you'll need to use this image instead:

itzg/minecraft-bedrock-server⁠

⁠Interacting with the server

RCON⁠ is enabled by default, so you can exec into the container to access the Minecraft server console:

docker exec -i mc rcon-cli

Note: The -i is required for interactive use of rcon-cli.

To run a simple, one-shot command, such as stopping a Minecraft server, pass the command as arguments to rcon-cli, such as:

docker exec mc rcon-cli stop

The -i is not needed in this case.

If rcon is disabled you can send commands by passing them as arguments to the packaged mc-send-to-console script. For example, a player can be op'ed in the container mc with:

docker exec mc mc-send-to-console op player
            |                     |
            +- container name     +- Minecraft commands start here

In order to attach and interact with the Minecraft server, add -it when starting the container, such as

docker run -d -it -p 25565:25565 --name mc itzg/minecraft-server

With that you can attach and interact at any time using

docker attach mc

and then Control-p Control-q to detach.

For remote access, configure your Docker daemon to use a tcp socket (such as -H tcp://0.0.0.0:2375) and attach from another machine:

docker -H $HOST:2375 attach mc

Unless you're on a home/private LAN, you should enable TLS access⁠.

⁠Data Directory

Everything the container manages is located under the container's /data path, as shown here:

NOTE: The container path /data is pre-declared as a volume, so if you do nothing then it will be allocated as an anonymous volume. As such, it is subject to removal when the container is removed.

⁠Attaching data directory to host filesystem

In most cases the easier way to persist and work with the minecraft data files is to use the -v argument to map a directory on your host machine to the container's /data directory, such as the following where /home/user/minecraft-data would be a directory of your choosing on your host machine:

docker run -d -v /home/user/minecraft-data:/data ...

When attached in this way you can stop the server, edit the configuration under your attached directory and start the server again to pick up the new configuration.

With Docker Compose, setting up a host attached directory is even easier since relative paths can be configured. For example, with the following docker-compose.yml Docker will automatically create/attach the relative directory minecraft-data to the container.

version: "3"

services:
  mc:
    image: itzg/minecraft-server
    ports:
      - 25565:25565
    environment:
      EULA: "TRUE"
    tty: true
    stdin_open: true
    restart: unless-stopped
    volumes:
      # attach a directory relative to the directory containing this compose file
      - ./minecraft-data:/data

NOTE: if you have SELinux enabled, then you might need to add :Z to the end of volume mount specifications, as described here⁠.

⁠Converting anonymous /data volume to named volume

If you had used the commands in the first section, without the -v volume attachment, then an anonymous data volume was created by Docker. You can later bring over that content to a named or host attached volume using the following procedure.

In this example, it is assumed the original container was given a --name of "mc", so change the container identifier accordingly.

First, stop the existing container:

docker stop mc

Use a temporary container to copy over the anonymous volume's content into a named volume, "mc" in this case:

docker run --rm --volumes-from mc -v mc:/new alpine cp -avT /data /new

Now you can recreate the container with any environment variable changes, etc by attaching the named volume created from the previous step:

docker run -d -it --name mc-new -v mc:/data -p 25565:25565 -e EULA=TRUE -e MEMORY=2G itzg/minecraft-server

⁠Versions

To use a different Minecraft version, pass the VERSION environment variable (case sensitive), which can have the value

  • LATEST (the default)
  • SNAPSHOT
  • or a specific version, such as "1.7.9"

For example, to use the latest snapshot:

docker run -d -e VERSION=SNAPSHOT ...

or a specific version:

docker run -d -e VERSION=1.7.9 ...

When using "LATEST" or "SNAPSHOT" an upgrade can be performed by simply restarting the container. During the next startup, if a newer version is available from the respective release channel, then the new server jar file is downloaded and used. NOTE: over time you might see older versions of the server jar remain in the /data directory. It is safe to remove those.

⁠Running Minecraft server on different Java version

When using the image itzg:/minecraft-server without a tag, the latest image tag is implied from the table below. To use a different version of Java, please use an alternate tag to run your Minecraft server container.

Tag nameJava versionLinuxJVM TypeArchitecture
latest17DebianHotspotamd64,arm64,armv7
java88AlpineHotspotamd64
java8-multiarch8DebianHotspotamd64,arm64,armv7
java8-openj98DebianOpenJ9amd64
java1111DebianHotspotamd64,arm64,armv7
java11-openj911DebianOpenJ9amd64
java16-openj916DebianOpenJ9amd64
java1717UbuntuHotspotamd64,arm64,armv7

For example, to use Java version 8 on any supported architecture:

docker run --name mc itzg/minecraft-server:java8-multiarch

Keep in mind that some versions of Minecraft server, such as Forge before 1.17, can't work on the newest versions of Java. Instead, one of the Java 8 images should be used. Also, FORGE doesn't support openj9 JVM implementation.

Some versions of vanilla Minecraft, such as 1.10, also do not run correctly with Java 17. If in doubt, use java8-multiarch for any version less than 1.17.

⁠Deprecated Image Tags

The following image tags have been deprecated and are no longer receiving updates:

  • adopt13
  • adopt14
  • adopt15
  • openj9-nightly
  • multiarch-latest
  • java16

⁠Healthcheck

This image contains mc-monitor⁠ and uses its status command to continually check on the container's. That can be observed from the STATUS column of docker ps

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                    PORTS                                 NAMES
b418af073764        mc                  "/start"            43 seconds ago      Up 41 seconds (healthy)   0.0.0.0:25565->25565/tcp, 25575/tcp   mc

You can also query the container's health in a script friendly way:

> docker container inspect -f "{{.State.Health.Status}}" mc
healthy

Some orchestration systems, such as Portainer, don't allow for disabling the default HEALTHCHECK declared by this image. In those cases you can approximate the disabling of healthchecks by setting the environment variable DISABLE_HEALTHCHECK to true.

⁠Deployment Templates and Examples

⁠Helm Charts
⁠Examples

The examples directory⁠ also provides examples of deploying the itzg/minecraft-server⁠ Docker image.

⁠Amazon Web Services (AWS) Deployment

If you're looking for a simple way to deploy this to the Amazon Web Services Cloud, check out the Minecraft Server Deployment (CloudFormation) repository⁠. This repository contains a CloudFormation template that will get you up and running in AWS in a matter of minutes. Optionally it uses Spot Pricing so the server is very cheap, and you can easily turn it off when not in use.

⁠Using Docker Compose

Rather than type the server options below, the port mappings above, etc every time you want to create new Minecraft server, you can now use Docker Compose⁠. Start with a docker-compose.yml file like the following:

version: "3"

services:
  mc:
    image: itzg/minecraft-server
    ports:
      - 25565:25565
    environment:
      EULA: "TRUE"
    tty: true
    stdin_open: true
    restart: unless-stopped

and in the same directory as that file run

docker-compose up -d

Now, go play...or adjust the environment section to configure this server instance.

⁠Troubleshooting

To troubleshoot the container initialization, such as when server files are pre-downloaded, set the environment variable DEBUG to true. The container logs will include much more output, and it is highly recommended including that output when reporting any issues⁠.

To troubleshoot just the command-line used to start the Minecraft server, set the environment variable DEBUG_EXEC to true.

To troubleshoot any issues with memory allocation reported by the JVM, set the environment variable DEBUG_MEMORY to true.

⁠Server types

⁠Running a Forge Server

Enable Forge server⁠ mode by adding a -e TYPE=FORGE to your command-line.

The overall version is specified by VERSION, as described in the section above⁠ and will run the recommended Forge version by default. You can also choose to run a specific Forge version with FORGEVERSION, such as -e FORGEVERSION=14.23.5.2854.

docker run -d -v /path/on/host:/data \
    -e TYPE=FORGE \
    -e VERSION=1.12.2 -e FORGEVERSION=14.23.5.2854 \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

To use a pre-downloaded Forge installer, place it in the attached /data directory and specify the name of the installer file with FORGE_INSTALLER, such as:

docker run -d -v /path/on/host:/data ... \
    -e FORGE_INSTALLER=forge-1.11.2-13.20.0.2228-installer.jar ...

To download a Forge installer from a custom location, such as your own file repository, specify the URL with FORGE_INSTALLER_URL, such as:

docker run -d -v /path/on/host:/data ... \
    -e FORGE_INSTALLER_URL=http://HOST/forge-1.11.2-13.20.0.2228-installer.jar ...

In both of the cases above, there is no need for the VERSION or FORGEVERSION variables.

⁠Running a Fabric Server

Enable Fabric server⁠ mode by adding a -e TYPE=FABRIC to your command-line. By default, the container will install the latest fabric-loader⁠ using the latest fabric-installer⁠, against the minecraft server version you have defined with VERSION (defaulting to the latest vanilla release of the game).

docker run -d -v /path/on/host:/data \
    -e TYPE=FABRIC \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

See the Working with mods and plugins⁠ section to set up Fabric mods and configuration.

A specific loader version other than the latest can be requested using FABRIC_LOADER_VERSION, such as:

docker run -d -v /path/on/host:/data ... \
    -e FABRIC_LOADER_VERSION=0.12.8

If you wish to use an alternative installer you can:

  • Specify an alternative version using FABRIC_INSTALLER_VERSION (such as -e FABRIC_INSTALLER_VERSION=0.10.2)
  • Provide the path to a custom installer jar available to the container with FABRIC_INSTALLER, relative to /data (such as -e FABRIC_INSTALLER=fabric-installer-0.5.0.32.jar)
  • Provide the URL to a custom installer jar with FABRIC_INSTALLER_URL (such as -e FABRIC_INSTALLER_URL=http://HOST/fabric-installer-0.5.0.32.jar)
⁠Running a Bukkit/Spigot server

Enable Bukkit/Spigot server mode by adding a -e TYPE=BUKKIT or -e TYPE=SPIGOT to your command-line.

docker run -d -v /path/on/host:/data \
    -e TYPE=SPIGOT \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

If you are hosting your own copy of Bukkit/Spigot you can override the download URLs with:

  • -e BUKKIT_DOWNLOAD_URL=
  • -e SPIGOT_DOWNLOAD_URL=

You can build spigot from source by adding -e BUILD_FROM_SOURCE=true

Plugins can either be managed within the plugins subdirectory of the data directory⁠ or you can also attach a /plugins volume⁠. If you add plugins while the container is running, you'll need to restart it to pick those up.

You can also auto-download plugins using SPIGET_RESOURCES.⁠

NOTE some of the VERSION values are not as intuitive as you would think, so make sure to click into the version entry to find the exact version needed for the download. For example, "1.8" is not sufficient since their download naming expects 1.8-R0.1-SNAPSHOT-latest exactly.

⁠Running a Paper server

Enable Paper server mode by adding a -e TYPE=PAPER to your command-line.

By default the container will run the latest build of Paper server⁠ but you can also choose to run a specific build with -e PAPERBUILD=205.

docker run -d -v /path/on/host:/data \
    -e TYPE=PAPER \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

If you are hosting your own copy of Paper you can override the download URL with:

  • -e PAPER_DOWNLOAD_URL=

An example compose file is provided at examples/docker-compose-paper.yml⁠.

If you have attached a host directory to the /data volume, then you can install plugins via the plugins subdirectory. You can also attach a /plugins volume⁠. If you add plugins while the container is running, you'll need to restart it to pick those up.

You can also auto-download plugins using SPIGET_RESOURCES.⁠

⁠Running an Airplane server

An Airplane⁠ server, which is "a stable, optimized, well supported 1.17 Paper fork."

-e TYPE=AIRPLANE

NOTE: The VERSION variable is used to select an Airplane branch to download from. The available options are "LATEST" "1.17" "1.16" "PURPUR" and "PURPUR-1.16"

Extra variables:

  • AIRPLANE_BUILD=lastSuccessfulBuild : set a specific Airplane build to use
  • FORCE_REDOWNLOAD=false : set to true to force the located server jar to be re-downloaded
  • USE_FLARE_FLAGS=false : set to true to add appropriate flags for the Flare⁠ profiler
⁠Running a Purpur server

A Purpur⁠ server, which is "drop-in replacement for Paper servers designed for configurability, new fun and exciting gameplay features, and performance built on top of Airplane."

-e TYPE=PURPUR

NOTE: the VERSION variable is used to lookup a build of Purpur to download

Extra variables:

  • PURPUR_BUILD=LATEST : set a specific Purpur build to use
  • FORCE_REDOWNLOAD=false : set to true to force the located server jar to be re-downloaded
  • USE_FLARE_FLAGS=false : set to true to add appropriate flags for the Flare⁠ profiler
⁠Running a Magma server

A Magma⁠ server, which is a combination of Forge and PaperMC, can be used with

-e TYPE=MAGMA

By default, the "stable" channel is used, but you can set MAGMA_CHANNEL to "dev" to access dev channel versions.

NOTE there are limited base versions supported, so you will also need to set VERSION, such as "1.12.2", "1.16.5", etc.

⁠Running a Mohist server

A Mohist⁠ server can be used with

-e TYPE=MOHIST

**NO

Tag summary

Content type

Image

Digest

Size

390.2 MB

Last updated

almost 5 years ago

docker pull spion06/minecraft-server