mcserver

A production-oriented Docker image for running a Minecraft Java server as a non-root user, with the server JAR downloaded at container startup.

Highlights

• Runs as a dedicated non-root user.
• Downloads server.jar from JAR_URL at startup with retry support.
• Supports optional checksum verification via JAR_SHA256.
• Stores all mutable server state under /data.
• Includes hardened example run scripts for both Java server and proxy workflows.

Quick start

Pull the image

docker pull ghcr.io/hauntedmc/mcserver:latest

Use the example runner (recommended)

cp examples/run-minecraft-server.sh ./run-mcserver.sh
chmod +x ./run-mcserver.sh
# Edit JAR_URL and other config values first
./run-mcserver.sh

For proxy deployments (for example Velocity), use examples/run-proxy-server.sh. That script sets MC_NOGUI=false because Velocity does not accept the --nogui startup argument. For internal-only Docker network deployments, set ENABLE_JAVA_PORT="false" in either example script.

Minimal manual run

docker run \
  --name minecraft-server \
  --restart unless-stopped \
  -d \
  -p 25565:25565/tcp \
  -p 25565:25565/udp \
  -e JVM_MEMORY=8G \
  -e JAR_URL='https://example.com/path/to/server.jar' \
  -v "$PWD/data:/data" \
  ghcr.io/hauntedmc/mcserver:latest

To keep the server internal-only on Docker network, omit the -p flags.

Documentation

• Configuration reference: docs/configuration.md
• Operations guide: docs/operations.md
• Runtime and script reference: docs/runtime-reference.md
• Project structure and naming conventions: docs/project-structure.md

Development

Run repository checks:

./scripts/validate.sh --with-docker-build

Build locally:

./build.sh

Bump release version and create tag:

./update_version.sh patch

Release tags

Pushing a version tag such as v1.2.3 publishes:

• ghcr.io/hauntedmc/mcserver:latest
• ghcr.io/hauntedmc/mcserver:v1.2.3
• ghcr.io/hauntedmc/mcserver:1.2.3
• ghcr.io/hauntedmc/mcserver:sha-<commit>

Community and policy

• Contributing: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• License: LICENSE