k8s 中文文档
Build and Publish


Expand to see deprecated docs sections -- soon will be removed## Intro

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 Versionssection below for more information.

To simply use the latest stable version, run

  1. ``` sh
  2. docker run -d -it -p 25565:25565 -e EULA=TRUE itzg/minecraft-server

  4. ```

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.


DO NOTport forward RCON on 25575 without first setting RCON_PASSWORD to a secure value. It is highly recommended to only use RCON within the container, such as with rcon-cli.


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.

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:

  1. ``` sh
  2. docker exec -i mc rcon-cli

  4. ```

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:

  1. ``` sh
  2. docker exec mc rcon-cli stop

  4. ```

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:

  1. ``` shell
  2. docker exec mc mc-send-to-console op player
  3.             |                     |
  4.             +- container name     +- Minecraft commands start here
  5. ```

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

  1. ``` sh
  2. docker run -d -it -p 25565:25565 --name mc itzg/minecraft-server

  4. ```

With that you can attach and interact at any time using

  1. ``` sh
  2. docker attach mc

  4. ```

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:

  1. ``` sh
  2. docker -H $HOST:2375 attach mc

  4. ```

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 bea directory on your host machine:

  1. ``` sh
  2. -v /home/user/minecraft-data:/data
  3.    ------------------------- -----
  4.     |                         |
  5.     |                         +-- must always be /data
  6.     |
  7.     +-- replace with a directory on your host machine

  9. ```

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.

  1. ``` yaml
  2. version: "3"

  4. services:
  5.   mc:
  6.     image: itzg/minecraft-server
  7.     ports:
  8.       - 25565:25565
  9.     environment:
  10.       EULA: "TRUE"
  11.     tty: true
  12.     stdin_open: true
  13.     restart: unless-stopped
  14.     volumes:
  15.       # attach a directory relative to the directory containing this compose file
  16.       - ./minecraft-data:/data
  17. ```

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:

  1. ``` shell
  2. docker stop mc
  3. ```

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

  1. ``` shell
  2. docker run --rm --volumes-from mc -v mc:/new alpine cp -avT /data /new
  3. ```

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

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

Locating filesystem path of anonymous volume


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

  1. ``` shell
  2. docker inspect -f "{{json .Mounts}}" CONTAINER_NAME_OR_ID
  3. ```

NOTEOn 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:

  1. ``` sh
  2. docker run -d -e VERSION=SNAPSHOT ...

  4. ```

or a specific version:

  1. ``` sh
  2. docker run -d -e VERSION=1.7.9 ...

  4. ```

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 mustuse 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
java20-alpine 19 Alpine Hotspot amd64
java20 19 Ubuntu Hotspot amd64,arm64,armv7

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

  1. ``` sh
  2. docker run --name mc itzg/minecraft-server:java8-multiarch

  4. ```

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:

java19
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-monitor


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

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

  5. ```

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

  1. ``` sh
  2. > docker container inspect -f "{{.State.Health.Status}}" mc
  3. healthy

  5. ```

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:

  1. ``` yaml
  2. healthcheck:
  3.   test: mc-health
  4.   start_period: 1m
  5.   interval: 5s
  6.   retries: 20
  7. ```

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


itzg Helm Chart:
GitHub repo
Helm Chart repo

mcsh/server-deployment

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:

  1. ``` yaml
  2. version: "3"

  4. services:
  5.   mc:
  6.     image: itzg/minecraft-server
  7.     ports:
  8.       - 25565:25565
  9.     environment:
  10.       EULA: "TRUE"
  11.     tty: true
  12.     stdin_open: true
  13.     restart: unless-stopped
  14. ```

and in the same directory as that file run

  1. ``` sh
  2. docker-compose up -d

  4. ```

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 moreoutput, 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.

  1. ``` sh
  2. docker run -d -v /path/on/host:/data \
  3.     -e TYPE=FORGE \
  4.     -e VERSION=1.12.2 -e FORGE_VERSION=14.23.5.2854 \
  5.     -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

  7. ```

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:

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

  5. ```

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

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

  5. ```

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.

  1. ``` sh
  2. docker run -d -v /path/on/host:/data \
  3.     -e TYPE=FABRIC \
  4.     -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

  6. ```

By default, the container will install the latest fabric server launcher, using the latest fabric-loader against the minecraft version you have de