# itzg/docker-minecraft-server: a Docker image that installs the server for you

> The image handles Java version selection, modloaders and modpacks at container start. This review covers what it automates, where it gets in the way, and what to check before putting a world on it.

**itzg/docker-minecraft-server** — Docker image that provides a Minecraft Server for Java Edition that automatically installs/upgrades versions, modloaders, modpacks and more at startup

- Repository: https://github.com/itzg/docker-minecraft-server
- Website: https://docker-minecraft-server.readthedocs.io/
- Stars: 14,358 · Forks: 1,922
- Language: Shell
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/itzg-docker-minecraft-server

## The problem: a Minecraft server is a build pipeline, not a binary

A vanilla Minecraft server jar is easy to download and hard to keep correct. The jar is tied to a Java runtime version. Modded servers replace it with a loader such as Forge, Fabric or NeoForge, each with its own installer. Modpacks add a manifest, a set of mod files and a matching loader version. Every one of those moving parts has to agree, and the agreement changes when the pack updates.

itzg/docker-minecraft-server moves that assembly work into container startup. The README describes the image as one that "automatically installs/upgrades versions, modloaders, modpacks and more at startup". The audience is anyone who already has Docker or Docker Compose on a machine and would rather write a declarative file than run an installer by hand: self-hosters, small friend groups, and hosting platforms. The README's sponsor list includes Server.pro and Seedloaf, both of which describe themselves as running on this image, which tells you the intended use ranges from a laptop to a paid hosting product.

The image is Java Edition only. The README is explicit that Bedrock needs a different image, itzg/minecraft-bedrock-server, or a compatibility layer documented under misc/examples.

## What the container does between docker compose up and a joinable world

The startup scripts read environment variables, resolve a server type, fetch the matching server artifact and Java runtime, then write server.properties from the properties you set. The Dockerfile shows the base is eclipse-temurin:25-jre, with the Java runtime supplied by the base image and the platform-specific package installation handled by build/run.sh install-packages.

Three small tools are baked in and pinned by version in the Dockerfile: easy-add, restify and rcon-cli, each pulled from the itzg GitHub releases and kept current by Renovate annotations. restify is the piece that makes server.properties configurable from environment variables, and rcon-cli is what lets you send console commands into a running server over RCON. The image also copies gosu into /usr/local/bin, which is how the entrypoint drops from root to the unprivileged user created by build/run.sh setup-user.

Data lives in a single volume, /data, mounted in the repository's own docker-compose.yml as a named volume called data. Worlds, configs, mods and logs all sit there, so the volume is the unit you back up. The image exposes port 25565, the standard Java Edition port.

## Installing it and getting a first server running

The repository ships a docker-compose.yml at the top level, and the README points to a quick start with Docker Compose in the documentation. That file is the shortest path to a working server: it sets the EULA environment variable to true, maps port 25565, mounts the data volume, keeps stdin and a tty open so you can attach to the console, and sets restart: unless-stopped.

```yaml
services:
  mc:
    image: itzg/minecraft-server
    environment:
      EULA: "true"
    ports:
      - "25565:25565"
    volumes:
      - data:/data
    stdin_open: true
    tty: true
    restart: unless-stopped
volumes:
  data: {}
```

Start it with docker compose up -d from the directory holding that file. On first run the container downloads the server jar into /data and accepts the EULA you declared. Watch the log until the server reports it is done loading, then connect a Java Edition client to the host on port 25565.

Adding a modloader is a matter of one more variable. The examples directory contains files such as examples/docker-compose-forge.yml and examples/docker-compose-fabric-cardboard/, and the documentation covers types and platforms for the full list. A Forge server, for instance, is the same service with TYPE set.

```yaml
environment:
  EULA: "true"
  TYPE: "FORGE"
  VERSION: "1.20.1"
```

Modpacks follow the same pattern through a provider. The examples include docker-compose-curseforge.yml and docker-compose-curseforge-atm7.yaml, which shows the CurseForge route with a pack identifier rather than a list of individual mods. Set the provider and the pack, and the container resolves the files at startup.

## Where the image pushes work back onto you

Startup is doing real network work. Every container start can involve checking a version manifest, downloading a server jar, and for a modpack, pulling many mod files. That means a restart is not instant, and a start that fails partway leaves you reading logs rather than seeing a clear error in a UI. The README does not document rollback, so if an automatic upgrade to a newer pack version breaks a world, recovering means restoring the /data volume from your own backup, not running a command.

Version pinning is therefore the operator's job. The image will resolve a version for you, and that convenience is exactly the risk for a long-lived world. Pinning VERSION and the modpack identifier in your compose file is the only thing standing between a restart and an unintended upgrade.

The image is also not a management interface. There is no web console in this repository; the console is the container's stdin and tty, and remote command execution is rcon-cli over RCON. People searching for a Docker Minecraft server manager should understand that the manager is your compose file and your shell, not a dashboard.

Bedrock clients are out of scope natively. The README directs Bedrock users to itzg/minecraft-bedrock-server or to a documented compatibility setup, so a group mixing Bedrock and Java clients needs extra work that this image alone does not provide.

## How it compares with a dedicated server panel

The obvious alternative is a game panel such as Pterodactyl or a hosted control panel, which gives you a browser UI, per-server user accounts and a file editor. The difference in approach is where configuration lives. A panel stores server definitions in its own database and drives the server through its own daemon; this image stores the definition in a compose file and drives the server through environment variables read at startup.

That makes the image a better fit for infrastructure-as-code habits. A compose file goes in git, gets reviewed, and reproduces the same server on another host. A panel is a better fit when non-technical people need to start and stop servers, or when you are hosting for many users and want quotas and isolation handled for you. The image gives you neither accounts nor quotas.

If you want a desktop app instead of Docker, the README's sponsor section names SpawnBox, a Windows desktop application built on this image for people who do not want to learn Docker, WSL2 or networking. That is a legitimate answer for the same problem, with the trade-off that you inherit someone else's packaging.

## Licence, maintenance and the cost of upgrades

The repository is Apache-2.0. That permits commercial use and modification, and it includes a patent grant, but it also means you must keep the licence and notice files when you redistribute. Running the published image on your own hardware is ordinary use; building a modified image and shipping it as part of a product is where the notice obligations start to matter. This is not legal advice, and if you plan to resell a service on top of the image, read the licence text in the repository rather than a summary.

The project is not archived, and the last push was on 2026-09-19. Releases are frequent and dated: 2026.9.1 on 2026-09-12, 2026.9.0 on 2026-09-05, 2026.8.2 on 2026-08-23. The version scheme is calendar-based, so the release number tells you the year and month directly. Renovate annotations in the Dockerfile track the bundled helper tools, which means the pinned versions of easy-add, restify and rcon-cli move without you doing anything when you pull a newer image tag.

The upgrade cost you actually pay is on the Minecraft side, not the image side. Pulling a newer image is cheap. Letting that image resolve a newer modpack or loader version against an existing world is the expensive part, and the project offers no rollback for it. Pin your versions, and keep a copy of the /data volume outside the host.

## Console access, autopause and the examples worth reading first

The examples directory is the most useful part of the repository for anyone past the first run. Alongside the Forge, Fabric and CurseForge files there are folders for autopause and autostop, which are the mechanisms for not burning CPU on an idle server; bentobox, bettermc and canyon, which are modpack setups; and docker-compose-world-download.yml, which shows bringing an existing world in rather than generating a fresh one.

Console access works in two directions. Attaching to the container's stdin gives you the interactive console, which is why the shipped compose file sets stdin_open and tty. For scripted commands, rcon-cli is installed in the image and talks to the server over RCON, which is the route to use from a cron job or a health check. The examples include docker-compose-rconcmd.yml for exactly that pattern.

One practical caveat about attaching: the tty is a convenience for a single operator, not a shared console. Two people attached at once will see each other's keystrokes, and detached restarts drop the session. If you need a persistent view of server output, read the container logs instead.

## Conclusion

Adopt itzg/docker-minecraft-server if you already run Docker and want a Java Edition server whose version, loader and mods are declared in environment variables rather than clicked through a panel. Skip it if you need Bedrock natively, or if you want a web console maintained by the same project. Verify first that your chosen server type and modpack are covered by the types-and-platforms documentation, and that your host has enough RAM for the pack you pick.

## FAQ

### Can I run a Minecraft server on Docker with itzg/docker-minecraft-server?

Yes. The repository ships a top-level docker-compose.yml that starts the itzg/minecraft-server image, sets EULA to true, maps port 25565 and mounts a data volume for the world.

### How do I set up a docker minecraft server with this image?

Use the compose file from the repository, run docker compose up -d, and wait for the server to finish loading before connecting a Java Edition client on port 25565. Server type, version and modpacks are then added as environment variables.

### How do I update a docker minecraft server running itzg/minecraft-server?

The image resolves and installs server versions, modloaders and modpacks at startup, so pulling a newer image tag and restarting the container is the update path. The README does not document rollback, so pin VERSION and the modpack identifier if you need to stay on a known working set.

### How do I stop a docker minecraft server?

The container is a normal Docker service, so docker compose stop or docker compose down stops it. The shipped compose file uses restart: unless-stopped, which means a stopped container stays stopped until you start it again.

### Does itzg/docker-minecraft-server support Bedrock and Java together?

Not natively. The README states the image only supports Java Edition, and points Bedrock users to itzg/minecraft-bedrock-server or to a documented compatibility setup under misc/examples.

## Sources

- [itzg/docker-minecraft-server on GitHub](https://github.com/itzg/docker-minecraft-server)
- [License: Apache-2.0](https://github.com/itzg/docker-minecraft-server/blob/master/LICENSE)
- [Project website](https://docker-minecraft-server.readthedocs.io/)
- [README](https://github.com/itzg/docker-minecraft-server/blob/master/README.md)
- [Releases](https://github.com/itzg/docker-minecraft-server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/itzg-docker-minecraft-server