ulicraft-server-v1/plan/05-minecraft.md

Minecraft server — itzg NeoForge

Summary

itzg/minecraft-server:java21, NeoForge 1.21.1, offline-mode + authlib-injector pointing at drasl. Mods come from a local ./server-mods volume (mounted at /mods), NOT packwiz — see 04-mods.md. itzg installs MC + NeoForge + libraries on first boot and auto-syncs /mods → /data/mods every boot; the stack assumes the internet is present (for the NeoForge installer), so TYPE=NEOFORGE boots normally every time.

Server config

TYPE=NEOFORGE, VERSION=1.21.1, NEOFORGE_VERSION=21.1.x
REMOVE_OLD_MODS=TRUE          # ./server-mods is the authoritative mod set
volume  ./server-mods:/mods:ro

./server-mods is populated by tooling/sync-server-mods.sh (the both/server subset of mods-sides.json, copied from $DISTRIBUTION_WEB_ROOT). First boot installs MC + NeoForge + libraries into the mc_data volume; every boot itzg mirrors /mods into /data/mods and prunes removed ones (REMOVE_OLD_MODS).

Auth / config

ONLINE_MODE=TRUE
ENFORCE_SECURE_PROFILE=FALSE                 # pairs with drasl SignPublicKeys=false
JVM_OPTS=-javaagent:/extras/authlib-injector.jar=http://auth.${BASE_DOMAIN}/authlib-injector

authlib URL uses the auth subdomain; resolves internally via the caddy alias. (Server still needs the agent even though Fjord clients have it built in.)

ONLINE_MODE MUST be true. authlib-injector works by redirecting the server's normal online-auth handshake from Mojang to Drasl. With ONLINE_MODE=FALSE the server skips that handshake entirely → players get offline-hash UUIDs, no session validation, and no skins (the server never fetches textures from Drasl). The thing that must stay off for 1.21+ is the secure profile (ENFORCE_SECURE_PROFILE=FALSE + Drasl SignPublicKeys=false), not online-mode. Symptom of getting this wrong: everyone can join but everyone is Steve, and usercache.json shows offline-hash UUIDs.

Memory: INIT_MEMORY 4G, MAX_MEMORY 10G, USE_AIKAR_FLAGS TRUE. RCON enabled for mc-backup.

Server operators (OP)

Do NOT use the itzg OPS env var. It resolves usernames to UUIDs via a Mojang lookup, but this server is ONLINE_MODE=TRUE validated against Drasl — Drasl assigns its own UUIDs (not Mojang, not the offline-hash). A Mojang-resolved UUID would not match the player's real session UUID, so the op entry would be inert (and could clobber a correct ops.json on reboot).

Op via RCON instead. The player must have connected at least once so their real Drasl UUID is cached in /data/usercache.json; then op <name> writes that cached UUID to ops.json. On the host:

ssh cochi
docker exec minecraft rcon-cli list                 # confirm cache / who's on
docker exec minecraft sh -c 'cat /data/usercache.json'   # verify name→UUID cached
docker exec minecraft rcon-cli op <name>
docker exec minecraft sh -c 'cat /data/ops.json'    # verify level 4 + right UUID

ops.json lives in the mc_data volume → persists across restarts; no reboot needed (takes effect live). Current op: oier (7fbc9adb-bcf4-3913-9a99-46d46acd1009), level 4, set 2026-06-21.

Simple Voice Chat — voice_host (NOT repo-tracked)

Voice chat is UDP 24454/udp, published in compose. The mod auto-generates /data/config/voicechat/voicechat-server.properties in the mc_data volume.

Gotcha — voice_host must be set or remote clients get a red/crossed icon. Behind any NAT/Docker the server announces an address for clients' UDP connection; if voice_host= is empty it auto-detects the internal Docker IP → unreachable → the secret (TCP) is sent but the UDP handshake never completes ("Sent secret" with no following "successfully connected to voice chat").

Set on prod:

docker exec minecraft sed -i 's/^voice_host=.*/voice_host=ulicraft.net/' \
  /data/config/voicechat/voicechat-server.properties
docker restart minecraft   # mod reads props only at startup

⚠️ This value lives in the mc_data volume, NOT auto-managed from this repo. It survives restarts and compose down/up, but a world wipe / fresh mc_data regenerates the file with voice_host= empty → voice silently breaks again.

A known-good prod snapshot is committed at server-configs/voicechat-server.properties (reference copy, voice_host=ulicraft.net). After a world reset, either re-run the sed + docker restart above, or restore the snapshot:

docker cp server-configs/voicechat-server.properties \
  minecraft:/data/config/voicechat/voicechat-server.properties
docker restart minecraft

(Snapshot is not auto-mounted — to make it durable, add a bind mount of server-configs/voicechat-server.properties into /data/config/voicechat/ in compose.)

Verify after a client joins: docker logs minecraft 2>&1 | grep -i "connected to voice" → expect Player <name> ... successfully connected to voice chat.

Note: a red voice icon can ALSO be client-side — a VPN/zero-trust client (Cloudflare One/WARP, FortiClient) on the player's machine silently drops the voice UDP. Rule out VPNs before touching the server.

Tasks

• Compose: authlib URL http://auth.${BASE_DOMAIN}/authlib-injector
• Compose: mount ./server-mods:/mods:ro + REMOVE_OLD_MODS=TRUE
• Run tooling/sync-server-mods.sh before bring-up (populates ./server-mods)
• Mount ./runtime for authlib-injector.jar at /extras
• depends_on: drasl (authlib must resolve at boot)
• Confirm ENFORCE_SECURE_PROFILE=FALSE ↔ drasl SignPublicKeys=false
• Verify a client joins with their drasl skin
• After any world wipe: re-set voice_host (see Simple Voice Chat section)