Add itzg-based docker-compose for live-testing the mod against real MC servers

Three services (mc-1_12_2 default, mc-1_7_10/mc-neoforge-26_1 opt-in via Compose profiles) using itzg/docker-minecraft-server, with mods/config bind- mounted per loader/version (mods/<loader>/<version>/) so jars can be dropped in and swapped without touching the compose file. Verified against real containers: fixed a WSL docker credential-helper misconfig blocking pulls, and pinned legacy Forge services to the java8 image tag after itzg's :latest (Java 25) crashed LaunchWrapper with a ClassCastException — mc-1_12_2 now boots cleanly to "Done" on java8.
2026-08-10 06:08:49 +02:00
parent 376d2d0507
commit 6e2739672c
10 changed files with 253 additions and 0 deletions
@@ -0,0 +1,121 @@
+# Real Minecraft servers for live-testing the mod against a running MCMapper-Backend stack —
+# see README.md in this directory for the full walkthrough (build the mod, seed a backend server
+# token, drop the jar in mods/<loader>/<version>/, docker compose up). Mods are split by loader
+# first, then version — Forge and NeoForge mod jars aren't interchangeable even for adjacent MC
+# versions, and a future Fabric leaf (Phase 14) would add its own mods/fabric/<version> alongside
+# these rather than needing a reshuffle.
+#
+# Uses itzg/docker-minecraft-server (https://github.com/itzg/docker-minecraft-server, MIT) — the
+# de facto standard MC server image, handles EULA/Forge/NeoForge installation, memory flags, etc.
+# so this compose file doesn't have to reimplement any of that.
+#
+# Only `mc-1_12_2` (the actual driving use case — Enigmatica 2, see the plan's version priority)
+# runs by default. The other two leaves are opt-in via Compose profiles, since running all three
+# at once is a lot of RAM for a local dev box:
+#   docker compose up                          # 1.12.2 only (default)
+#   docker compose --profile legacy-1_7_10 up   # + 1.7.10
+#   docker compose --profile neoforge-26_1 up   # + 26.1.2 (NeoForge) — least tested, lowest MVP priority
+
+services:
+  mc-1_12_2:
+    # itzg's `:latest` tag now defaults to a Java 25 base — legacy Forge's LaunchWrapper hard-
+    # crashes on anything past Java 8 (`ClassCastException: AppClassLoader cannot be cast to
+    # URLClassLoader`, confirmed by actually booting this service against `:latest` first). Same
+    # JDK 8 constraint as this repo's own build toolchain (see ../gradle.properties), just for the
+    # server *runtime* instead of the compiler this time.
+    image: itzg/minecraft-server:java8
+    tty: true
+    stdin_open: true
+    ports:
+      - "${MC_1_12_2_PORT:-25565}:25565"
+    environment:
+      EULA: "TRUE"
+      TYPE: "FORGE"
+      VERSION: "1.12.2"
+      # Same build pinned in ../gradle.properties (forge_1_12_2_version) — keep these in sync.
+      FORGE_VERSION: "14.23.5.2847"
+      MEMORY: "${MC_1_12_2_MEMORY:-3G}"
+      # Offline/cracked mode by default so any MC client can connect with no Microsoft account
+      # needed for a quick local smoke test — matches the plan's authMode="offline" identity
+      # scoping (see MCMapper-Backend's README). Flip to TRUE (and register the backend server
+      # row with authMode=online) to test the real online-mode UUID-merge path instead.
+      ONLINE_MODE: "${MC_1_12_2_ONLINE_MODE:-FALSE}"
+    volumes:
+      - mc-1_12_2-data:/data
+      # Drop the built forge-1_12_2 jar (see README.md — `./gradlew :forge-1_12_2:build`,
+      # output in ../forge-1_12_2/build/libs/) — and any other mod jars to stress-test against
+      # (e.g. Thaumcraft, the plan's named Phase 13 non-cube-model target) — straight into this
+      # directory; itzg's image loads anything here as-is, no repackaging needed. Add/remove jars
+      # any time and `docker compose restart mc-1_12_2` to pick up changes.
+      - ./mods/forge/1.12.2:/data/mods
+      # The mod writes config/mcmapper.cfg here on first boot (see the mod repo README's
+      # "Configuration" section) — edit backendUrl/serverToken in this mounted file, then
+      # `docker compose restart mc-1_12_2`.
+      - ./config/forge/1.12.2:/data/config
+    # Lets `backendUrl=ws://host.docker.internal:<port>/ws` in the mounted config reach a backend
+    # stack running on the host (either MCMapper-Backend's own `docker compose up`, published on
+    # host port 80 via its Caddy, or a bare `bun run dev` api on host port 3000) — see README.md.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+
+  mc-1_7_10:
+    # Same Java-8 requirement as mc-1_12_2 above — 1.7.10's Forge/LaunchWrapper generation is
+    # even older, so it needs this at least as much.
+    image: itzg/minecraft-server:java8
+    profiles: ["legacy-1_7_10"]
+    tty: true
+    stdin_open: true
+    ports:
+      - "${MC_1_7_10_PORT:-25566}:25565"
+    environment:
+      EULA: "TRUE"
+      TYPE: "FORGE"
+      VERSION: "1.7.10"
+      # Same build pinned in ../gradle.properties (forge_1_7_10_version).
+      FORGE_VERSION: "10.13.4.1614-1.7.10"
+      MEMORY: "${MC_1_7_10_MEMORY:-2G}"
+      ONLINE_MODE: "${MC_1_7_10_ONLINE_MODE:-FALSE}"
+    volumes:
+      - mc-1_7_10-data:/data
+      - ./mods/forge/1.7.10:/data/mods
+      - ./config/forge/1.7.10:/data/config
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+
+  mc-neoforge-26_1:
+    # Unlike the two legacy leaves above, this one actually *wants* a modern JRE (Minecraft
+    # itself requires Java 25 as of the 26.x cycle, see ../neoforge-26_1/settings.gradle) — plain
+    # `:latest` already resolves to a java25 base as of this writing (confirmed by actually
+    # pulling it), so no separate tag pin needed here.
+    image: itzg/minecraft-server:latest
+    profiles: ["neoforge-26_1"]
+    tty: true
+    stdin_open: true
+    ports:
+      - "${MC_NEOFORGE_26_1_PORT:-25567}:25565"
+    environment:
+      EULA: "TRUE"
+      TYPE: "NEOFORGE"
+      VERSION: "26.1.2"
+      # Same build pinned in ../gradle.properties (neoforge_26_1_version). This is the least
+      # exercised leaf (lowest MVP priority, see the plan) — if itzg's installer doesn't yet
+      # recognize this exact MC/NeoForge version pairing, check for an itzg image update first.
+      NEOFORGE_VERSION: "26.1.2.94"
+      MEMORY: "${MC_NEOFORGE_26_1_MEMORY:-3G}"
+      ONLINE_MODE: "${MC_NEOFORGE_26_1_ONLINE_MODE:-FALSE}"
+    volumes:
+      - mc-neoforge-26_1-data:/data
+      - ./mods/neoforge/26.1.2:/data/mods
+      # NeoForge writes config/mcmapper-server.toml (TOML, not the legacy leaves' .cfg) — see
+      # the mod repo README's "Configuration" section.
+      - ./config/neoforge/26.1.2:/data/config
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+
+volumes:
+  mc-1_12_2-data:
+  mc-1_7_10-data:
+  mc-neoforge-26_1-data: