papermc-docker

Last reviewed Aug 26, 2026 · 818 words

The itzg image is how nearly everyone runs Minecraft Java in Docker, and the one setting that separates a happy server from a corrupted world is not in the image at all. Docker gives a container 10 seconds to shut down before it sends SIGKILL. A Paper server with a few players and a large world can take longer than that to flush chunks to disk. Set stop_grace_period before you invite anyone.

The whole tutorial genre fits in one compose file

Every "how to host Minecraft on Linux" article from the last decade collapses into this:

services:
  mc:
    image: itzg/minecraft-server
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: LATEST
      MEMORY: 3G
      USE_AIKAR_FLAGS: "true"
      TZ: Europe/London
    volumes:
      - ./data:/data
    stop_grace_period: 1m
    restart: unless-stopped

On first start the image downloads the right Java, the right Paper build for the requested version, accepts the EULA because you said so, and writes server.properties from environment variables. Everything persistent lives in /data: world, plugins, configs, logs. Back that directory up and the container itself is disposable. Setting TYPE to FORGE, FABRIC, PURPUR or a dozen others swaps the server flavour; VERSION: 1.21.1 pins a release instead of tracking the newest, which is what you want the moment a plugin you rely on lags behind an update. The official documentation is unusually good and covers every knob.

Memory: the 1 GB floor is a floor, not a target

The catalogue lists 1,024 MB as the minimum and that is honest for a vanilla server with 1 or 2 players and a fresh world. It is not enough for Paper with a handful of plugins, and it is nowhere near enough for a Forge modpack, which routinely wants 6 to 8 GB. MEMORY: 3G sets both -Xms and -Xmx; USE_AIKAR_FLAGS adds the G1GC tuning that the Paper project itself recommends and it removes most of the garbage-collection stutter people blame on "lag". Leave at least 1 GB of host RAM above whatever you give the JVM, because Java uses more than its heap. The con in the catalogue, "Java memory tuning needed", is really just those two lines; get them right once and you are done.

Plugins and mods install themselves from environment variables

You can drop jars into /data/plugins by hand, but the image can fetch them for you at start. SPIGET_RESOURCES takes a comma-separated list of SpigotMC resource IDs, MODRINTH_PROJECTS takes Modrinth slugs for Fabric and Paper content, and PLUGINS or MODS take plain URLs. For a Fabric server with a couple of quality-of-life mods that means the whole build is reproducible from the compose file, which matters more than it sounds: when a friend asks for "the same server", you send them 20 lines of YAML rather than a 400 MB tarball. The one behaviour to know is that removing an entry from the list does not remove the jar from /data; clean up old plugins yourself.

Bedrock players need a different image, or Geyser

The image in this listing runs Java Edition. Phones and consoles speak Bedrock, and the maintainer publishes a separate itzg/minecraft-bedrock-server for that. If you want one world for both audiences, run a Paper server here and add the GeyserMC plugin plus Floodgate, which translate the Bedrock protocol on the fly. It works well for survival play; it is not perfect for combat-heavy minigames where the two editions' mechanics diverge. Expose UDP 19132 in addition to TCP 25565 when you do this.

When a panel earns its keep

For one server for one group of friends, the compose file above is the right amount of tooling, and docker compose logs -f mc plus docker exec mc rcon-cli covers administration. The point where a panel starts to pay for itself is around 3 servers or when people who cannot SSH need to restart things. Crafty Controller is the lightest step up and uses ordinary server jars; Pterodactyl is the full hosting-company experience with per-server containers, user accounts and resource limits, and is heavier than the game it manages. Both are covered in the games category. Under the hood the itzg image is still what many people run inside those panels' eggs, so nothing you learn here is wasted.

What I'd do

Paper via the itzg image, VERSION pinned to the release my plugins support, 3 to 4 GB of memory with Aikar's flags, stop_grace_period: 1m, and a nightly tar of /data shipped off the box while the server is stopped or after save-all over RCON. Keep ONLINE_MODE at its default of true so accounts are verified against Mojang. Fourteen thousand stars and a decade of releases mean the sharp edges are documented; the only ones left are the ones you skip.