Dockercraft

A Docker image for running Minecraft servers with support for multiple loaders.

Features

• Multi-loader support — Vanilla, Paper, Fabric, Forge, NeoForge, and Bedrock
• Auto-detection — Java version and loader versions are auto-detected from Mojang manifests
• Persistent data — Server files, worlds, and Java installations are stored in /data
• Health checks — Built-in container health monitoring
• Flexible Java — Pin or auto-detect Java version (Temurin, Zulu, GraalVM, etc.)
• Bedrock support — Native Bedrock Dedicated Server without Java

Quick Start

services:
  minecraft:
    image: git.jeremymcclure.com/jeremy/dockercraft:latest
    container_name: minecraft
    stdin_open: true
    tty: true
    environment:
      - EULA=true
      - MC_VERSION=1.21.1
      - MC_LOADER=neoforge
      - MC_LOADER_VERSION=21.1.185
      - JAVA_VERSION=temurin@21
      - XMS=2G
      - XMX=4G
      - PUID=1000
      - PGID=1000
    volumes:
      - ./data:/data
    ports:
      - 25565:25565
    restart: unless-stopped

Environment Variables

Variable	Default	Description
EULA	—	Required. Set to true to accept the Minecraft EULA
MC_VERSION	—	Minecraft version (e.g., 1.21.1). Required for Java loaders; auto-detected for Bedrock
MC_LOADER	—	Required. Server loader: vanilla, paper, fabric, forge, neoforge, or bedrock
MC_LOADER_VERSION	—	Fallback version for any loader
FABRIC_LOADER_VERSION	$MC_LOADER_VERSION	Fabric loader version
FORGE_VERSION	$MC_LOADER_VERSION	Forge version (e.g., 52.1.14)
NEOFORGE_VERSION	$MC_LOADER_VERSION	NeoForge version (e.g., 21.1.185)
PAPER_BUILD	latest	Paper build number (auto-detects latest stable if unset)
JAVA_VERSION	auto-detected	Java version (via Jabba, e.g., temurin@21, zulu@17). Auto-detects from Mojang manifest if unset: 1.20.5+→21, 1.17-1.20.4→17, 1.17→16, pre-1.17→8
JAR	server.jar	Server jar filename
XMS	2G	Initial Java heap size
XMX	4G	Maximum Java heap size
ADD_ARGS	—	Additional Java arguments
PUID	1000	User ID for /data ownership
PGID	1000	Group ID for /data ownership

Supported Loaders

Loader	Description	Ports
Vanilla	Official Mojang server	TCP 25565
Paper	High-performance fork from papermc.io	TCP 25565
Fabric	Lightweight mod loader via fabricmc.net	TCP 25565
Forge	Mod loader via minecraftforge.net	TCP 25565
NeoForge	Community fork of Forge via neoforged.net	TCP 25565
Bedrock	Official Bedrock Dedicated Server (no Java)	UDP 19132

Volumes

• /data — Persists server data, worlds, config, and Java installations

Loader-Specific Examples

Paper

environment:
  - EULA=true
  - MC_VERSION=1.21.1
  - MC_LOADER=paper
  - PAPER_BUILD=132  # optional, auto-detects latest stable

Fabric

environment:
  - EULA=true
  - MC_VERSION=1.21.1
  - MC_LOADER=fabric
  - FABRIC_LOADER_VERSION=0.19.3  # optional, auto-detects latest

Forge / NeoForge

environment:
  - EULA=true
  - MC_VERSION=1.21.1
  - MC_LOADER=forge        # or neoforge
  - FORGE_VERSION=52.1.14  # optional, auto-detects latest

Bedrock

environment:
  - EULA=true
  - MC_LOADER=bedrock
  - MC_VERSION=1.21.50     # Bedrock server version
ports:
  - 19132:19132/udp
  - 19133:19133/udp        # IPv6 (optional)

Java Version Management

Java is managed via Jabba. Java installations are cached in /data/java/ so they persist across container restarts.

Supported distributions include temurin, zulu, adopt, openjdk, graalvm, and more. Use the format distribution@version:

- JAVA_VERSION=temurin@21
- JAVA_VERSION=zulu@17
- JAVA_VERSION=graalvm@21

If unset, the Java version is auto-detected from the Mojang version manifest based on MC_VERSION.

Health Checks

The container includes a built-in health check:

• Java servers — TCP check on port 25565
• Bedrock servers — UDP check on port 19132

The health check has a 2-minute start period to allow the server time to initialize.

Troubleshooting

Server fails to start

Check the container logs:

docker logs minecraft

EULA not accepted

If you see an EULA error, make sure EULA=true is set in your environment variables.

Java not found

If Java installation fails, check that the /data volume is writable. Java is installed to /data/java/ on first run.

Wrong UID/GID

If you get permission errors on server files, check that PUID and PGID match your host user:

id -u  # your UID
id -g  # your GID

Port conflicts

Make sure the Minecraft port (25565 for Java, 19132 for Bedrock) is not already in use:

ss -tlnp | grep 25565

Development

Building locally

docker build -t dockercraft:local .

Running tests

API tests — verify all external APIs are healthy and returning correct data (no Docker needed):

# All suites
./tests/run_tests.sh

# Specific MC version
./tests/run_tests.sh -m 1.21.1

# Specific suites only
./tests/run_tests.sh -s mojang,fabric,neoforge

Integration tests — spin up Docker containers and verify full download → install → server start:

# Test all loaders
./tests/integration.sh

# Test a specific loader
./tests/integration.sh -m 1.21.1 -l fabric

# Custom timeout
./tests/integration.sh -t 300

License

See LICENSE for details.