How to Run a Minecraft Server in Docker with Compose

Running a server in a container turns it into a file you can read: the version, the memory, the settings and the data location are all written down in one place. Moving to a new machine means copying that file and a data folder. It also makes updates a matter of changing a line.

This guide uses the widely used itzg image, which installs and upgrades the server for you at startup.

What you need

Docker installed and working, with the Compose plugin, and a machine with enough memory for your server plus the operating system. You do not need to install Java yourself, because the image provides it.

The smallest working setup

The documentation's quick start for Compose is a file named compose.yaml with a service that uses the itzg image, publishes port 25565 and accepts the EULA through an environment variable:

• image: itzg/minecraft-server:latest
• ports: 25565:25565
• environment: EULA set to TRUE
• volumes: ./data mapped to /data

Run it with docker compose up -d and the server starts. Watch the log with docker compose logs -f until it reports it is done.

What each part does

EULA must be TRUE. The documentation explains that Mojang requires acceptance of its licence, so setting it is you agreeing; read the licence first.

The port mapping makes the server reachable on the standard port 25565. If another service already uses it, change the left-hand number and give players the new port.

The volume is the important one. The server keeps its world and settings in /data inside the container, and mapping a folder from your machine there keeps them when the container is removed or replaced. Without it, the documentation warns, the data is lost when the container stops. Never run a server you care about without it.

tty and stdin_open let you attach to the server console with docker attach or run commands with the image's tools.

Choose the server type and version

Environment variables select what runs. TYPE chooses the server variant, such as PAPER or FABRIC, and VERSION chooses the Minecraft version. Add them under environment. If you want plugins, TYPE: PAPER is the usual choice; our guide on choosing server software explains why.

Memory is set with the MEMORY variable. Leave headroom beyond it for the operating system and for Java's own use, because the container needs more than the heap.

Plugins, configuration and the data folder

The data folder you mapped holds everything: server.properties, the world, plugins and their configuration. Put plugin jars in the plugins folder inside it, or use the image's options for fetching them. The image can also set common server.properties values from environment variables, which keeps your settings in the compose file instead of scattered across files.

Updates

The documentation recommends pulling new images regularly. The example uses pull_policy: daily so Compose fetches a newer image when it starts. Two cautions:

• latest follows new releases, which may include a new Minecraft version. Pin a version tag or set VERSION when you want to stay put, and move on purpose.
• Back up the data folder before any update, as with any server.

To update deliberately, run docker compose pull followed by docker compose up -d.

Backups

A container does not back itself up. Copy the data folder on a schedule to somewhere off the machine, using a plugin or a scheduled job, and practise restoring it; our guide to backups explains how. Stopping the server or saving before you copy avoids inconsistent files.

When a container is not the right tool

If you only run one server on one machine and are comfortable starting it by hand, a container adds a layer to learn without much benefit. If you need a graphical panel for other people to manage servers, look at a panel instead; some panels use containers underneath.

Troubleshooting

• Container exits at once: read the log, and check EULA is TRUE.
• Cannot connect: check the port mapping and your firewall, and that you connect to the right machine.
• World gone after a restart: you did not map the volume. Recover from backups and fix the compose file.