Running Minecraft Proxies with Docker: A Practical Guide to itzg/docker-mc-proxy

If you’ve ever wanted to link multiple Minecraft servers together without juggling separate ports or complex scripts, a proxy is the answer. The itzg/docker-mc-proxy image lets you run BungeeCord, Velocity or Waterfall inside a container, making network setup as simple as a docker compose file.

What This Project Does (in user terms)

At its core the project provides a ready-made Docker image that launches a Minecraft proxy of your choice. You pick the type - BungeeCord for legacy plugins, Velocity for modern performance, or Waterfall for a Paper-based alternative - and the container handles the Java process, health checks and basic configuration. All you need to supply is a config.yml and any extra files you want mounted.

The image is built to work hand-in-hand with the popular itzg/minecraft-server image, but it’s not locked to that setup. Any server that speaks the Minecraft server list protocol can sit behind the proxy, whether it’s another Docker container, a vanilla jar on a VM, or even a third-party host.

Why You'd Use It (concrete Minecraft use cases)

Imagine running a survival world, a creative plot world and a mini-games hub, each on its own server jar. Without a proxy players would've to disconnect and reconnect to switch between them. Real talk, with a proxy in place you give players a single IP address, and the proxy silently forwards them to the correct backend based on the server name they use in their client.

Another common scenario is hosting a public lobby while keeping your private whitelist server hidden. The proxy can enforce online-mode checks on the lobby while leaving the backend in offline mode, a pattern that works well with the Minecraft MOTD Creator tool for customizing the lobby message.

If you enjoy experimenting with snapshots, you can run a 26.2 release server for stable play and a 26.3-snapshot-5 instance for testing new features, all behind the same proxy address. This keeps your community on one entry point while you stay on the latest.

How to Install (include real commands in fenced code blocks)

Assuming you already have Docker and Docker Compose installed, start by creating a folder for your project. Inside it place a file named docker-compose.yml with the following content:

version: '3'
services:
  lobby:
    image: itzg/minecraft-server
    environment:
      EULA: 'TRUE'
      ONLINE_MODE: 'FALSE'
    volumes:
      - lobby-data:/data
  proxy:
    image: itzg/mc-proxy
    environment:
      TYPE: VELOCITY
      VELOCITY_JAR_REVISION: '1'
      CFG_MOTD: 'Welcome to my network!'
      REPLACE_ENV_VARIABLES: 'true'
    ports:
      - '25565:25577'
    volumes:
      - ./velocity.toml:/config/velocity.toml
      - proxy-data:/server
volumes:
  lobby-data:
  proxy-data:

Bring the stack up with:

docker compose up -d

The proxy will listen on port 25565 and forward to the lobby container on its internal port. If you prefer BungeeCord just change the TYPE to BUNGEECORD and mount a config.yml instead of a TOML file.

For a quick test without compose you can run a single container:

docker run -d \\
  --name mc-proxy \\
  -e TYPE=BUNGEECORD \\
  -e CFG_MOTD='My BungeeCord Hub' \\
  -p 25565:25577 \\
  -v $(pwd)/config.yml:/config/config.yml \\
  -v proxy-data:/server \\
  itzg/mc-proxy

Remember to set ONLINE_MODE=FALSE on any backend server you intend to connect, otherwise the proxy will reject the connection.

Key Features and How They Work (3 - 5 standout features)

Multiple proxy types in one image - Rather than maintaining separate Dockerfiles for BungeeCord, Velocity and Waterfall, this project uses environment variables to decide which jar to download and launch. Switching between them is as easy as changing TYPE and restarting the container.

Automatic health checking - The image bundles mc-monitor and runs its status command every few seconds. Docker reports the container as healthy when the proxy responds, giving you instant visibility in docker ps or via docker container inspect -f '{{.State.Health.Status}}' proxy.

Easy icon and MOTD customization - Set ICON to a URL and the container will download, resize to 64×64 and place the file as server-icon.png. The CFG_MOTD variable lets you change the message of the day without editing config files, which pairs nicely with the Minecraft Block Search tool when you want to highlight a featured block in your motd.

Flexible JVM tuning - Variables like MEMORY, INIT_MEMORY, MAX_MEMORY, JVM_OPTS and JVM_XX_OPTS give you full control over the Java heap and garbage collection flags. If you leave MEMORY empty the image respects the container’s memory limit, a useful default for cloud hosts.

Volume-based persistence - All server-specific data (plugins, configs, worlds) is stored under /server. By mounting a host directory or a named volume you keep your proxy configuration safe across image updates.

Tips, Pitfalls, and Common Gotchas

One frequent mistake is forgetting to disable online mode on the backend when using BungeeCord or Velocity in offline mode. The proxy will still attempt to validate each login against Mojang’s servers, causing connection failures. Double-check that your server’s ONLINE_MODE environment variable is set to false.

Another gotcha involves the REPLACE_ENV_VARIABLES flag. If you set it to true the image will substitute placeholders like ${MOTD} in your config files before launching the proxy. This is powerful but can lead to unexpected values if you accidentally reuse the same variable name elsewhere. Always review the rendered config with docker exec proxy cat /server/config.yml after the container starts.

Healthchecks rely on the mc-monitor binary being able to talk to the proxy’s admin interface. If you change the proxy’s binding address or disable its admin port, the healthcheck will fail and Docker will mark the container unhealthy. In that case either revert the change or disable the healthcheck with healthcheck: none in your compose file.

Actually, the healthcheck only works when the proxy’s admin interface is exposed on the default port; if you map it elsewhere you need to adjust the monitor command. This small note saves you from debugging why a perfectly functional proxy shows as unhealthy.

Alternatives (1 - 3 similar Minecraft projects)

If you prefer a more lightweight solution, docker-bungeecord from the same maintainer focuses solely on BungeeCord and skips the extra abstraction layers. It’s a good fit when you never plan to switch proxy types.

The official Velocity Docker images provided by PaperMC are another option. They give you direct control over the Velocity version but require you to write your own startup script and healthcheck.

For users who enjoy a full-featured control panel, itzg/docker-minecraft-server includes a proxy mode that bundles both server and proxy in a single compose example, reducing the number of separate containers you need to manage.