Skip to content

DOCKER_SETUP.md

Latest commit

 

History

History
145 lines (102 loc) · 3.79 KB

DOCKER_SETUP.md

File metadata and controls

145 lines (102 loc) · 3.79 KB

Docker Setup for Minecraft Fabric Mod

This guide explains how to build and deploy your Minecraft Fabric mod using Docker.

Prerequisites

  1. Docker installed on your system
  2. Java 21 for building the mod
  3. Fabric server launcher jar file

Setup Steps

1. Download Fabric Server Launcher and API

Download both the Fabric server launcher and Fabric API for Minecraft 1.21.7:

# Use the provided download script (downloads both files)
./download-fabric-server.sh

# Or download manually:
# Fabric Server Launcher
wget https://meta.fabricmc.net/v2/versions/loader/1.21.7/0.16.14/1.0.3/server/jar -O fabric-server-launch.jar

# Fabric API (create mods directory first)
mkdir -p mods
wget "https://cdn.modrinth.com/data/P7dR8mSH/versions/VjIVvVhW/fabric-api-0.128.1%2B1.21.7.jar" -O mods/fabric-api-0.128.1+1.21.7.jar

2. Accept Minecraft EULA

cp eula.txt.example eula.txt
# Edit eula.txt and set eula=true

3. Configure Server Properties (Optional)

cp server.properties.example server.properties
# Edit server.properties as needed

Build Commands

Build with Gradle

# Build the mod jar
./gradlew build

# Build Docker image using Gradle tasks
./gradlew dockerBuild

# Build and run Docker container
./gradlew dockerRun

# Push to registry (if configured)
./gradlew dockerPush

Build with Docker directly

# Build image
docker build -f minecraft.Dockerfile -t minecraft-fabric-mod .

# Run container
docker run -d -p 25565:25565 -p 7070:7070 -v minecraft_data:/minecraft minecraft-fabric-mod

Using Docker Compose (Recommended)

# Start the server with persistent volumes
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Stop and remove volumes (WARNING: This deletes world data)
docker-compose down -v

Available Gradle Docker Tasks

  • ./gradlew dockerBuild - Build Docker image
  • ./gradlew dockerRun - Build and run container (stops existing first)
  • ./gradlew dockerStop - Stop and remove running container
  • ./gradlew dockerLogs - View container logs
  • ./gradlew dockerPush - Push image to registry
  • ./gradlew dockerCompose - Start services using docker-compose

Ports Exposed

  • 25565: Minecraft server port
  • 7070: API server port for mod endpoints

Volumes

  • /minecraft - Full server home (persistent)

The container now keeps packaged binaries and default config templates inside the image under /opt/minecraft-dist, then syncs them into the live /minecraft volume on startup. Runtime state such as ops.json, whitelist.json, banned-players.json, banned-ips.json, world data, and logs persists across container recreation.

On startup, the container:

  • refreshes the server launcher and packaged mod jars from the image
  • creates server.properties and eula.txt only if they do not already exist in the volume
  • preserves operator-managed files already present in /minecraft

API Endpoints

Once running, the mod API will be available at:

  • http://localhost:7070/api/world/players
  • http://localhost:7070/api/world/entities
  • http://localhost:7070/api/world/blocks/*
  • http://localhost:7070/api/message/*

Troubleshooting

Container won't start

  1. Check EULA acceptance in eula.txt
  2. Verify Fabric server jar is present
  3. Check Docker logs: docker-compose logs minecraft

API not responding

  1. Check if port 7070 is exposed
  2. Verify mod is loaded correctly
  3. Check server logs for errors

Memory issues

  1. Adjust JAVA_OPTS in docker-compose.yml
  2. Increase Docker memory limits
  3. Monitor with docker stats

Development

For development, you can mount your mod directly:

# Add to docker-compose.yml volumes:
- ./build/libs:/opt/minecraft-dist/mods

Then rebuild your mod and restart the container to test changes.