DEV Community

Cover image for 🐳 Minecraft + Docker: My personal config to stop suffering with Java
Tomás Alegre Sepúlveda
Tomás Alegre Sepúlveda

Posted on

🐳 Minecraft + Docker: My personal config to stop suffering with Java

🇪🇸 Lee este post en Español

I'm no Java guru, and I'll be honest: managing Minecraft servers has always felt like a weird puzzle to me. Even though Minecraft might look like a "random" game about placing blocks, the technical management behind a server (threads, memory, garbage collection) is a fascinating optimization challenge.

Back in the day, I tried creating plugins (with... "interesting" results), but I learned the hard way that the real battle is almost always the configuration.

Has this happened to you? You want to play Survival with friends, you search for "best paper 1.21 config", and you end up with 20 open tabs and three wikis that contradict each other.

The Initiative: Enough Chaos

Tired of copying and pasting the same configuration lines over and over again, I decided to build Paper Config Optimized.

I didn't want to make "just another guide". I wanted a place to truly centralize the community's best practices into ready-to-use files. In fact, I've become such a fan of this "infrastructure as code" approach that I recently made my first contribution to the official Docker image repository we use (PR #3076 in itzg/docker-minecraft-server) and plan to keep contributing to improve the ecosystem.

"The Recipe" (Configuration)

Here is the configuration I always use. It's basically my "copy, paste, and forget" template.

The important thing here is that we are telling Docker two key things:

  1. "Use Aikar's Flags": So Java doesn't get picky with memory.
  2. "Download configs from the repo": So the game runs smoothly without having to touch anything.
services:
  mc:
    image: itzg/minecraft-server
    container_name: paper-lite
    restart: unless-stopped
    ports:
      - "25565:25565"

    # Interactive console (never hurts to see what's happening)
    stdin_open: true
    tty: true

    environment:
      # Mojang bureaucracy and software choice (Paper flies)
      EULA: "TRUE"
      TYPE: "PAPER"

      # Always the latest. Living on the edge.
      VERSION: "LATEST"

      # We activate Aikar's flags.
      # Trust me, you don't want to manage the Garbage Collector manually.
      USE_AIKAR_FLAGS: "true"

      # Timezone (change to yours so logs make sense)
      TZ: "America/Santiago"

      # ✨ THE MAGIC:
      # Automatically injects optimized configs from the repo at startup.
      PAPER_CONFIG_REPO: "https://raw.githubusercontent.com/Alpha018/paper-config-optimized/main"

    volumes:
      - ./minecraft-data:/data
Enter fullscreen mode Exit fullscreen mode

How to run this?

It's as simple as putting that into a docker-compose.yml file, opening a terminal in the folder, and throwing in a:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

⚖️ Balance: Pros and Cons

As with everything in engineering, there are no silver bullets. This configuration is my favorite, but we have to be transparent:

✅ The Good (Pros)

  • Speed: Go from "zero" to "optimized server" in 2 minutes.
  • Maintenance: By using PAPER_CONFIG_REPO, if performance improvements come out tomorrow, you just have to restart the container to apply them.
  • Stability: Using Aikar's Flags eliminates 90% of lag spikes caused by Java.

❌ The Bad (Cons)

  • Black Box: If you like manually adjusting every millimeter of view-distance, you might feel like you're losing some control (although you can always overwrite the files).
  • Dependency: You depend on my repository (or your own fork) being online to download the configs at startup.

🚀 For Advanced Users

This configuration is ideal for what I call "Lite Technical Survival". But if you are planning to set up a massive public community (50+ players) or want to understand why 12GB of RAM is my magic number for large servers, I wrote a much deeper technical guide.

Check out the Advanced Technical Guide on Buy Me a Coffee


💌 Special Acknowledgments

To a girl who, without knowing it, pushed me to keep creating and coding in my free time. To the one who was once my spark: for "YLP", with gratitude... and with scars that also teach.

Top comments (0)