8000 GitHub - TORQDL/docker-minecraft-server: Docker image that provides a Minecraft Server that will automatically download selected version at startup
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

TORQDL/docker-minecraft-server

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1,637 Commits
.github
.github
 
 
bin
bin
 
 
build
build
 
 
docs
docs
 
 
examples
examples
 
 
files
files
 
 
kustomize
kustomize
 
 
scripts
scripts
 
 
tests
tests
 
 
.dockerignore
.dockerignore
 
 
.editorconfig
.editorconfig
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
BUILDING.md
BUILDING.md
 
 
DEVELOPMENT.md
DEVELOPMENT.md
 
 
Dockerfile
Dockerfile
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 

Repository files navigation

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.

Mitigated Log4jShell Vulnerability

Please ensure you have pulled the latest image since all official mitigations are automatically applied by the container startup process.

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 easiest way to persist and work with the minecraft data files is to use the volume mounting -v argument to map a directory on your host machine to the container's /data directory. In the following example, the path /home/user/minecraft-data must be a directory on your host machine:

-v /home/user/minecraft-data:/data
   ------------------------- -----
    |                         |
    |                         +-- must always be /data
    |
    +-- replace with a directory on your host machine

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.

You can also locate the Docker-managed directory from the Source field obtained from docker inspect <container id or name> -f "{{json .Mounts}}"

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

Locating filesystem path of anonymous volume

The Source field from the output of this command will show where the anonymous volume is mounted from:

docker inspect -f "{{json .Mounts}}" CONTAINER_NAME_OR_ID

NOTE On Windows with WSL the volumes path is \\wsl$\docker-desktop-data\data\docker\volumes

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

For Forge versions less than 1.18, you must use the java8-multiarch (or other java8) image tag.

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 name Java version Linux JVM Type Architecture
latest 17 Ubuntu Hotspot amd64,arm64,armv7
java8 8 Alpine Hotspot amd64
java8-jdk 8 Ubuntu Hotspot+JDK amd64
java8-multiarch 8 Ubuntu Hotspot amd64,arm64,armv7
java8-openj9 8 Debian OpenJ9 amd64
java8-graalvm-ce 8 Oracle GraalVM CE amd64
java11 11 Ubuntu Hotspot amd64,arm64,armv7
java11-jdk 11 Ubuntu Hotspot+JDK amd64,arm64,armv7
java11-openj9 11 Debian OpenJ9 amd64
java17 17 Ubuntu Hotspot amd64,arm64,armv7
java17-jdk 17 Ubuntu Hotspot+JDK amd64,arm64,armv7
java17-openj9 17 Debian OpenJ9 amd64
java17-graalvm-ce 17 Oracle GraalVM CE amd64,arm64
java17-alpine 17 Alpine Hotspot amd64

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/java16-openj9

Related Projects

itzg/minecraft-bedrock-server

Docker image that runs a Minecraft Bedrock server.

mc-router

Lightweight multiplexer/proxy for Minecraft Java servers. Provided as a stand-alone application and a Docker image.

itzg/bungeecord

Docker image that runs a proxy powered by Bungeecord, Velocity, or Waterfall

itzg/mc-backup

Docker image that runs as a side-car container to backup world data.

rcon-cli

A tool that is bundled with this image to provide CLI access to an RCON endpoint.

mc-m BEA9 onitor

A tool that is bundled with this image that provides health checks and metrics reporting, such as a Prometheus exporter or a telegraf data source.

mc-image-helper

A tool that is bundled with this image to provide complex, re-usable preparation operations.

itzg/rcon

An image that dockerizes rcon-web-admin.

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

There's actually a wrapper script called mc-health that takes care of calling mc-monitor status with the correct arguments. If needing to customize the health checks parameters, such as in a compose file, then use something like the following in the service declaration:

healthcheck:
  test: mc-health
  start_period: 1m
  interval: 5s
  retries: 20

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 FORGE_VERSION, such as -e FORGE_VERSION=14.23.5.2854.

docker run -d -v /path/on/host:/data \
    -e TYPE=FORGE \
    -e VERSION=1.12.2 -e FORGE_VERSION=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.

If an error occurred while installing Forge, it might be possible to resolve by temporarily setting FORGE_FORCE_REINSTALL to "true". Be sure to remove that variable after successfully starting the server.

Running a Fabric Server

Enable Fabric server mode by adding a -e TYPE=FABRIC to your command-line.

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

By default, the container will install the latest fabric server launcher, using the latest fabric-loader against the minecraft version you have defined with VERSION (defaulting to the latest vanilla release of the game).

A specific loader or launcher version other than the latest can be requested using FABRIC_LOADER_VERSION and FABRIC_LAUNCHER_VERSION respectively, such as:

docker run -d -v /path/on/host:/data ... \
    -e TYPE=FABRIC \
    -e FABRIC_LAUNCHER_VERSION=0.10.2 \
    -e FABRIC_LOADER_VERSION=0.13.1

If you wish to use an alternative launcher you can:

  • Provide the path to a custom launcher jar available to the container with FABRIC_LAUNCHER, relative to /data (such as -e FABRIC_LAUNCHER=fabric-server-custom.jar)
  • Provide the URL to a custom launcher jar with FABRIC_LAUNCHER_URL (such as -e FABRIC_LAUNCHER_URL=http://HOST/fabric-server-custom.jar)

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

Running a Quilt Server

Enable Quilt server mode by adding a -e TYPE=QUILT to your command-line.

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

By default, the container will install the latest quilt server launcher, using the latest quilt-installer against the minecraft version you have defined with VERSION (defaulting to the latest vanilla release of the game).

A specific loader or installer version other than the latest can be requested using QUILT_LOADER_VERSION and QUILT_INSTALLER_VERSION respectively, such as:

docker run -d -v /path/on/host:/data ... \
    -e TYPE=QUILT \
    -e QUILT_LOADER_VERSION=0.16.0 \
    -e QUILT_INSTALLER_VERSION=0.4.1

If you wish to use an alternative launcher you can:

  • Provide the path to a custom launcher jar available to the container with QUILT_LAUNCHER, relative to /data (such as -e QUILT_LAUNCHER=quilt-server-custom.jar)
  • Provide the URL to a custom launcher jar with QUILT_LAUNCHER_URL (such as -e QUILT_LAUNCHER_URL=http://HOST/quilt-server-custom.jar)

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

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 PAPER_DOWNLOAD_URL=<url>.

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 a Pufferfish server

A Pufferfish server, which is "a highly optimized Paper fork designed for large servers requiring both maximum performance, stability, and "enterprise" features."

-e TYPE=PUFFERFISH

NOTE: The VERSION variable is used to select branch latest, 1.18, or 1.17. Use PUFFERFISH_BUILD to really select the SERVER VERSION number.

Extra variables:

  • PUFFERFISH_BUILD=lastSuccessfulBuild : set a specific Pufferfish build to use. Example: selecting build 47 => 1.18.1, or build 50 => 1.18.2 etc
  • 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 built-in Flare profiler

Running a Purpur server

A Purpur server, which is "a drop-in replacement for Paper servers designed for configurability and new, fun, exciting gameplay features."

-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 built-in Flare profiler
  • PURPUR_DOWNLOAD_URL=<url> : set URL to download Purpur from custom URL.

Running a Magma server

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

-e TYPE=MAGMA

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

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

By default the latest build will be used; however, a specific build number can be selected by setting MOHIST_BUILD, such as

-e VERSION=1.16.5 -e MOHIST_BUILD=374

Running a Catserver type server

A Catserver type server can be used with

-e TYPE=CATSERVER

NOTE Catserver only provides a single release stream, so VERSION is ignored

Running a Loliserver type server

A Loliserver type server can be used with

-e TYPE=LOLISERVER

NOTE Loliserver only provides a single release stream, so VERSION is ignored

Disclaimer The retrieval of the serverjar is not bulletproof. It can and probably will change in the future.

Running a Canyon server

Canyon is a fork of CraftBukkit for Minecraft Beta 1.7.3. It includes multiple enhancements whilst also retaining compatibility with old Bukkit plugins and mods as much as possible.

-e VERSION=b1.7.3 -e TYPE=CANYON

NOTE only VERSION=b1.7.3 is supported. Since that version pre-dates the health check mechanism used by this image, that will need to be disabled by setting DISABLE_HEALTHCHECK=true.

By default, the latest build will be used; however, a specific build number can be selected by setting CANYON_BUILD, such as

-e CANYON_BUILD=11

Running a SpongeVanilla server

Enable SpongeVanilla server mode by adding a -e TYPE=SPONGEVANILLA to your command-line.

By default the container will run the latest STABLE version. If you want to run a specific version, you can add -e SPONGEVERSION=1.11.2-6.1.0-BETA-19 to your command-line.

Beware that current Sponge STABLE versions for Minecraft 1.12 require using the Java 8 tag:

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

You can also choose to use the EXPERIMENTAL branch. Just change it with SPONGEBRANCH, such as:

$ docker run -d -v /path/on/host:/data ... \
    -e TYPE=SPONGEVANILLA -e SPONGEBRANCH=EXPERIMENTAL ...

Running a Limbo server

A Limbo server can be run by setting TYPE to LIMBO.

Configuration options with defaults:

  • LIMBO_BUILD=LATEST

    The VERSION will be ignored so locate the appropriate value from here to match the version expected by clients.

  • FORCE_REDOWNLOAD=false

  • LIMBO_SCHEMA_FILENAME=default.schem

  • LEVEL="Default;${LIMBO_SCHEMA

NAME}"

NOTE: instead of using format codes in the MOTD, Limbo requires JSON chat content. If a plain string is provided, which is the default, then it gets converted into the required JSON structure.

Running a Crucible server