How to Run a Minecraft Server in Docker

Why Docker for Minecraft

Docker wraps your Minecraft server, its Java runtime, configuration files, and world data into a self-contained unit called a container. The container runs the same way on your local machine, a VPS, a dedicated server, or a cloud instance. This makes minecraft server docker setups portable, reproducible, and easy to manage.

The practical benefits are immediate: no Java version conflicts (the container bundles its own JDK), easy backups (the world data lives in a Docker volume you can snapshot), clean updates (swap the container image, keep the volumes), and simple multi-server setups (run five containers on one machine, each isolated).

Prerequisites

Install Docker and Docker Compose on your host machine. On Ubuntu/Debian:

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect. Verify with docker --version and docker compose version.

Choosing an Image

The most popular and well-maintained minecraft server docker image is itzg/minecraft-server. It supports Paper, Spigot, Fabric, Forge, Purpur, Vanilla, and dozens of modpack launchers. It handles EULA acceptance, server type selection, Java version pinning, and auto-updating through environment variables.

Alternative images exist, but itzg/minecraft-server covers 95% of use cases and is actively maintained. We recommend starting there.

Basic docker-compose.yml

Create a directory for your server and a docker-compose.yml file:

mkdir ~/mc-docker && cd ~/mc-docker

services:
  minecraft:
    image: itzg/minecraft-server:latest
    container_name: mc-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "PAPER"
      VERSION: "1.21.4"
      MEMORY: "4G"
      VIEW_DISTANCE: 10
      MOTD: "Docker Minecraft Server"
    volumes:
      - ./data:/data
    restart: unless-stopped
    tty: true
    stdin_open: true

Start the server with:

docker compose up -d

The -d flag runs it in the background. View logs with docker compose logs -f. The server world, plugins, and configs are stored in ./data on your host filesystem.

Volume Management

The volumes directive maps the container's /data directory to ./data on your host. This is where your world files, plugin JARs, server.properties, and all configuration live. If you delete and recreate the container, your data persists because it is on the host filesystem, not inside the container.

For backups, simply archive the ./data directory:

tar -czf backup-$(date +%Y%m%d).tar.gz ./data

You can also use Docker named volumes instead of bind mounts, but bind mounts are easier to browse and back up directly.

Adding Plugins

Drop plugin JARs into ./data/plugins/ and restart the container:

docker compose restart

The itzg image also supports auto-downloading plugins by URL using the SPIGET_RESOURCES or MODRINTH_PROJECTS environment variables. For example, to auto-install EssentialsX via Modrinth:

environment:
  MODRINTH_PROJECTS: "essentialsx"

Networking

The ports directive maps port 25565 on your host to port 25565 in the container. If you run multiple minecraft server docker containers on one machine, map each to a different host port:

ports:
  - "25566:25565"  # Second server on port 25566

For a reverse proxy setup (BungeeCord or Velocity in front of multiple backend servers), use Docker's internal networking instead of exposing ports. Create a Docker network and connect all containers to it.

JVM Flags

Pass custom JVM flags through the JVM_XX_OPTS environment variable:

environment:
  JVM_XX_OPTS: "-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1"

See our JVM flags guide for the full recommended set and explanations.

Updating the Server

To update Minecraft or Paper version, change the VERSION environment variable and recreate the container:

docker compose down
docker compose pull
docker compose up -d

Your world data stays intact because it lives in the volume. The new container downloads the updated server JAR automatically.

Skip the hardware headaches. Astroworld Hosting runs NVMe SSDs, modern CPUs, and optimized configs on every plan.

Monitoring and Console Access

Attach to the Minecraft console:

docker attach mc-server

Detach with Ctrl+P then Ctrl+Q (do not use Ctrl+C, that stops the server). For resource monitoring, use docker stats mc-server to see CPU, RAM, and network usage in real time. For a more detailed monitoring setup, see our monitoring guide.

When Docker Adds Overhead

Docker's performance overhead is minimal, typically less than 1% for CPU and negligible for disk I/O when using bind mounts. The networking layer adds microseconds of latency, which is invisible to Minecraft players. The minecraft server docker approach is not slower than bare-metal in any measurable way for this workload. The main trade-off is complexity: if something goes wrong, you are debugging both Minecraft and Docker. For simple single-server setups, running directly on the host with systemd is equally valid.