migration_plan.md

Migration Plan: itzg/minecraft to Native Windows/Java

This document outlines the findings from researched the itzg/docker-minecraft-server repository and proposes a strategy for implementing its capabilities in a native Windows/Java environment.

1. Core Architecture Overview

The itzg/docker-minecraft-server project is primarily an orchestration layer implemented in Bash scripts that wrap around several high-level components:

• Helper Tools (Go-based): These tools are developed by itzg (Geoff Bourne) and are open-source. They are essential for handling the non-Java complexities of managing a Minecraft server.
  • mc-image-helper:
    • Source: GitHub - itzg/mc-image-helper
    • Role: The "Swiss Army Knife" for the server. It handles version resolution (mapping "latest" to a specific JAR), downloading server binaries, installing modloaders (Forge, Fabric, Quilt, etc.), and syncing with CurseForge/Modrinth API.
  • mc-server-runner:
    • Source: GitHub - itzg/mc-server-runner
    • Role: A process supervisor that wraps the Java execution. It ensures graceful shutdowns (sending stop to the console), maps system signals (SIGTERM) to server commands, and provides an optional RCON bridge and "auto-pause" functionality.
  • rcon-cli:
    • Source: GitHub - itzg/rcon-cli
    • Role: A simple CLI to send commands to the Minecraft server via the RCON protocol.
  • mc-monitor:
    • Source: GitHub - itzg/mc-monitor
    • Role: Performs health checks by pinging the Minecraft server port and reporting status/metrics.
  • easy-add:
    • Source: GitHub - itzg/easy-add
    • Role: A utility for downloading and extracting files from URLs/GitHub releases, used during the image build process to fetch the other helpers.
• Bash Scripts: Orchestrate the flow from initialization to final execution, translating environment variables into configuration files and command-line arguments.
• Java: The actual Minecraft server process.

2. Key Capabilities to Migrate

To achieve parity with the Docker implementation, the native Windows version must support:

• Automated Deployment: Downloading the selected server type (Vanilla, Paper, Forge, etc.) and version (Latest, Snapshot, specific version).
• Mod/Modpack Management: Support for CurseForge, Modrinth, and manual mod installation via environment-driven configuration.
• JVM Optimization: Automatic application of optimized JVM flags (Aikar's, MeowIce's) based on available memory and Java version.
• Configuration Management: Translating simple settings into server.properties, eula.txt, and other configuration files.
• Process Management: Clean startup/shutdown and RCON integration.

3. Proposed Native Windows Strategy

A. Environment & Distribution

• Portable Java: The implementation should bundle or allow easy selection of a portable JDK (e.g., Eclipse Temurin).
• Windows Binary Helpers: Utilize the existing Windows builds of mc-image-helper.exe and mc-server-runner.exe.

B. The "Bootstrapper" (Replaces Bash)

Instead of porting 40+ Bash scripts to PowerShell (which can be fragile across Windows versions/locales), a Java-based Bootstrapper is recommended.

Why Java?

• Self-Contained: Since Minecraft requires Java anyway, the bootstrapper adds no extra dependencies.
• Portability: Logic can be shared or easily adapted if other native platforms are targeted later.
• Maintainability: Strongly typed configuration and logic.

Bootstrapper Responsibilities:

1. Config Loading: Read a .env or config.properties file containing settings similar to the Docker environment variables.
2. Environment Setup: Set up necessary environment variables for the helper tools.
3. Deployment Phase: Invoke mc-image-helper.exe to ensure the server JAR and mods are present.
4. CLI Construction: Port the logic from start-finalExec to build the full java.exe command line (performance flags, memory settings, JMX, etc.).
5. Execution Phase: Invoke mc-server-runner.exe to start the server.

C. Directory Structure

A suggested layout for the native installation:

C:\MinecraftServer\
├── bin\
│   ├── mc-image-helper.exe
│   ├── mc-server-runner.exe
│   └── bootstrapper.jar
├── jdk\                (Optional: Bundled Java)
├── data\               (Equivalent to the Docker /data volume)
│   ├── world\
│   ├── mods\
│   └── server.properties
├── config.env          (User configuration)
└── start.bat           (Simple entry point to run the bootstrapper)

4. High-Level Native Workflow

The following diagram illustrates the lifecycle of the native implementation, from user configuration to server execution.

graph TD
    A["User Config (config.env)"] --> B["start.bat"]
    B --> C["Java Bootstrapper"]
    
    subgraph "Initialization Phase"
        C --> D["Validate Config & Environment"]
        D --> E["Ensure Binaries (mc-image-helper, mc-server-runner)"]
    end
    
    subgraph "Deployment Phase"
        E --> F["Invoke mc-image-helper.exe"]
        F --> G["Resolve Version"]
        G --> H["Download Server JAR & Mods"]
        H --> I["Update server.properties & EULA"]
    end
    
    subgraph "Execution Phase"
        I --> J["Construct JVM Arguments (Memory, Flags, JMX)"]
        J --> K["Invoke mc-server-runner.exe"]
        K --> L["Launch Minecraft (java.exe)"]
    end
    
    L --> M["Status Monitoring (mc-monitor)"]
    M --> N["Administration (rcon-cli)"]

Loading

5. Implementation Steps

1. Bootstrap Research: Finalize the list of environment variables and logic to be ported from Bash to Java.
2. Asset Gathering: Create a package containing the Windows binaries for mc-image-helper and mc-server-runner.
3. Bootstrapper Development:
   • Implement EnvironmentManager to handle config parsing.
   • Implement DeploymentManager to wrap callouts to mc-image-helper.
   • Implement JvmOptimizer to port the flag generation logic.
4. Service Integration (Optional): Provide a winsw or nssm configuration for running the server as a Windows Service.

5. Summary

The transition from Docker to Native Windows is highly feasible by leveraging the platform-agnostic Go helper tools already used in the Docker image. By replacing the Bash orchestration layer with a Java-based bootstrapper, we provide a robust, maintainable, and "natural" environment for Minecraft server administrators on Windows.