Minecraft Worlds

Quickstart: Bring a World Up

1. Create via Web Control Plane (https://mc.drheck.dev) or CLI (ipctl):

   • Web UI (Recommended): Open https://mc.drheck.dev, click + New World, style the world name/MOTD and 64×64 icon, preview/reroll the world seed with the live 2D biome map, and click Create & Provision World.
   • CLI (ipctl):

     sudo /data/minecraft/ipctl create <name> --dns
     

     (Allocates backend IPv6 fd77:7777:5010::1337:3c:d00d:<hex>/64 in /etc/systemd/network/20-wired.network.d/minecraft.conf, configures HAProxy SNI routing in /etc/haproxy/conf.d/minecraft_backends.cfg and /etc/haproxy/minecraft_hosts.map, adds <name>.drheck.dev to /var/unbound/etc/unbound.minecraft.conf on danknasty using a short-lived 5-minute step-ca SSH user certificate, and syncs public A/AAAA records to deSEC.io).

2. Configure the backend server: In your backend server's server.properties:

   server-ip=fd77:7777:5010::1337:3c:d00d:<hex>
   server-port=25565
   online-mode=true
   

   (Backend servers run with online-mode=true, listening on standard port 25565 on their dedicated ULA IPv6 address).

3. Start the server: Start via https://mc.drheck.dev (Start button or automatic On-Demand wake-on-join) or sudo systemctl start minecraft@<slug>.service.

4. Connect: Players connect using <name>.drheck.dev (standard port 25565). Microsoft account authentication takes place directly between the client and the backend server.

Quickstart: Take a World Down

1. Stop the backend server: Click Stop in https://mc.drheck.dev, send stop in the live web console, or run sudo systemctl stop minecraft@<slug>.service.

2. What Players See When Offline or Standby (On-Demand): HAProxy intercepts all Multiplayer Server List pings ($\text{state} = 1$) and offline/standby Login joins ($\text{state} = 2$) via /etc/haproxy/minecraft.lua and mc-manager:

   • In the Multiplayer Server List (state = 1): Returns the server's configured custom MOTD and 64×64 server-icon.png (favicon) immediately, with version status badge Standby (Join to Wake) (for ondemand servers) or Offline (for manual servers).
   • When Clicking "Join Server" (state = 2):
     • ondemand Standby: Automatically triggers minecraft@<slug>.service to boot and displays a gold countdown screen (Waking up <Server>... Ready in ~20s!).
     • manual Offline: Immediately disconnects with a clean red screen (<Server> is currently offline. Start at mc.drheck.dev).

3. Disable or remove router mapping & DNS (Teardown):

   • Temporary takedown (disable in router only):

     sudo /data/minecraft/ipctl route disable <name>
     

   • Complete teardown (release IP, remove HAProxy route, purge DNS):

     sudo /data/minecraft/ipctl delete <name> --dns
     

Architecture & Design Details

1. Unified Endpoint Model

All public and LAN client connections resolve to the single Minecraft Router endpoint pair:

• IPv4: 10.0.0.113 (NAT port-forwarded from WAN IPv4 :25565 on danknasty)
• IPv6: fd77:7777:5010::1337:f1ac:d00d:3c (dynamically mapped to GUA <gua_prefix>:1337:f1ac:d00d:3c in public DNS)

Whether connecting via pokelovers.drheck.dev, desertworld.drheck.dev, or any other server subdomain, players connect to this exact IP pair on standard port 25565.

2. Transparent TCP SNI Handshake Routing & Live Ping Injection (HAProxy + mc-manager)

Rather than using an application-level proxy (which breaks vanilla Diffie-Hellman encryption and forces online-mode=false), HAProxy performs transparent pre-handshake packet inspection:

1. HAProxy listens dual-stack on 10.0.0.113:25565 and [fd77:7777:5010::1337:f1ac:d00d:3c]:25565.
2. When a player connects, HAProxy peeks at the initial unencrypted Minecraft handshake packet (0x00) via /etc/haproxy/minecraft.lua and extracts the requested hostname (txn.mc_host, e.g. pokelovers.drheck.dev) and handshake state (txn.mc_state: 1 = Status Ping, 2 = Login Join).
3. For All Multiplayer Server List Pings ($\text{state} = 1$): Each backend uses the rule:

   tcp-request content use-service lua.mc_offline if { var(txn.mc_state) -m int eq 1 } || !{ nbsrv(<slug>) gt 0 }
   

   lua.mc_offline queries mc-manager (http://127.0.0.1:8095/internal/haproxy with STATUS <slug>). If the backend JVM is running, mc-manager queries the backend's live TCP status (0x00) to obtain real-time online player counts and version metadata, then overlays the latest motd from server.properties and favicon from /data/minecraft/<dir>/server-icon.png. This ensures MOTD styling and 64×64 icon changes saved in mc.drheck.dev appear immediately on client Refresh without restarting a running Minecraft server.
4. For Player Login Joins ($\text{state} = 2$):
   • If the backend server is UP: HAProxy splices the raw TCP stream directly to [fd77:7777:5010::1337:3c:d00d:<hex>]:25565. The client and backend perform native Microsoft/Mojang online-mode=true authentication directly over the spliced TCP connection.
   • If the backend server is DOWN: lua.mc_offline sends JOIN <slug> to mc-manager, which wakes ondemand servers automatically and returns a formatted Minecraft Disconnect packet (0x00).

3. Backend IPv6 Address Scheme & Active Worlds

Each backend Minecraft server is isolated on a dedicated Unique Local Address (ULA) on interface eth77 of ul:

• Prefix: fd77:7777:5010::1337:3c:d00d:<hex>/64
• Port: Each server binds to standard port 25565 on its assigned IPv6 address.
• Active Managed Worlds:

4. Web Map (BlueMap) & Authentik Gated HTTPS

Interactive 3D web mapping for Minecraft is powered by BlueMap running in standalone watch mode:

• Service: bluemap-pokelovers.service running from /data/minecraft/poke lovers/bluemap.
  • Automatically updates the rendered 3D map as chunks change in /data/minecraft/poke lovers/world.
  • Serves live map data & Server-Sent Events (SSE) updates on internal port 8100.
• Reverse Proxy & Authentication: NGINX terminates SSL on port 443 at /etc/nginx/sites-available/pokelovers and gates access behind Authentik ForwardAuth (/outpost.goauthentik.io/auth/nginx).
  • Serves directly at https://pokelovers.drheck.dev.
  • Unauthenticated visitors are automatically redirected to auth.drheck.dev to log in before viewing the 3D map.

5. Network & DNS Automation (ipctl) — Externalized Configs & Short-Lived SSH CA

To prevent dynamic Minecraft world provisioning from mutating code-reviewed host and router configuration files (/etc/systemd/network/20-wired.network, /etc/haproxy/haproxy.cfg, and /home/luke/git/router_config/unbound.conf), /data/minecraft/ipctl (symlinked at /home/luke/bin/ipctl) operates exclusively on dedicated external drop-in and include files:

Programmatic Short-Lived SSH CA Authentication (step-ca $\longrightarrow$ danknasty)

When /data/minecraft/ipctl is invoked with --dns (either interactively or unattended by mc-manager.service after a reboot when no ssh-agent is active):

1. ipctl generates a fresh ephemeral Ed25519 keypair in a mode-0700 temporary directory (atexit-cleaned).
2. ipctl requests a 5-minute (--not-after=5m) SSH user certificate for principal luke from the local step-ca container using the webshell-svc JWK provisioner (the same short-lived CA used by webshell.drheck.dev).
3. danknasty validates the certificate against TrustedUserCAKeys /etc/ssh/drheck_ca_user_key.pub (configured in /etc/sshd_config.d/10-drheck-certs.conf), allowing ipctl to update /var/unbound/etc/unbound.minecraft.conf, run doas unbound-checkconf and doas rcctl restart unbound, and invoke /home/luke/git/router_config/dns_danger_sync.py --force to synchronize public A and AAAA records to deSEC.io.
4. Both update_dns.py and dns_danger_sync.py (as well as verify_dns.sh) on danknasty recursively follow include: directives in unbound.conf, ensuring all external Minecraft subdomains are automatically included during prefix rotations and deSEC.io synchronization.

Backups & Disaster Recovery

Both the HAProxy router layer and the mc-manager control plane (including all external network, proxy, and DNS mirror files) are integrated into /home/luke/git/backups/ul/scripts/:

• Control Plane & External Network Backup: /home/luke/git/backups/ul/scripts/backup/mc_manager
  • Archives /data/minecraft/.manager, /data/minecraft/.network, /data/minecraft/ipctl, /usr/local/bin/{mc-manager,mc-runner,mc-seed-render}, /etc/systemd/system/{mc-manager.service,minecraft@.service}, /etc/systemd/network/20-wired.network.d/minecraft.conf, /etc/nginx/sites-available/mc, /etc/haproxy/minecraft.lua, /etc/haproxy/minecraft_hosts.map, and /etc/haproxy/conf.d/minecraft_backends.cfg with 10% par2 parity into /data/backups/services/current/mc_manager/.
• Control Plane Restore: /home/luke/git/backups/ul/scripts/restore/mc_manager [timestamp]
• Router Backup & Restore: /home/luke/git/backups/ul/scripts/backup/minecraft_router and /home/luke/git/backups/ul/scripts/restore/minecraft_router [timestamp]

6. Minecraft Server Manager & On-Demand Architecture (Production Architecture)

Production Control Plane: The unified web control plane at https://mc.drheck.dev (bound to [fd77:7777:5010::1337:f1ac:d00d:3c00]:8095 behind Nginx and Authentik ForwardAuth) manages all Minecraft worlds on ul, automates ipctl networking and systemd lifecycle management, wakes sleeping servers on-demand via HAProxy when players join, streams live PTY server consoles, and provides an integrated Seed Preview Studio and Text, MOTD, Color Gradient & 8-Bit Pixel Icon Studio.

6.1 Canonical Definition of a "Server"

Every managed Minecraft world on ul is a self-contained unit consisting of five standardized components:

$$\text{Server}(\text{slug}) = \left\lbrace\text{Directory}, \quad \text{Manifest } (\texttt{server.json}), \quad \text{Network } (\texttt{ipctl}), \quad \text{Units } (\texttt{systemd}), \quad \text{Lifecycle Policy}\right\rbrace$$

{
  "slug": "desertworld",
  "display_name": "⚔ 𝔇𝔢𝔰𝔢𝔯𝔱 𝔚𝔬𝔯𝔩𝔡 ⚔",
  "dir_name": "desertworld",
  "domain": "desertworld.drheck.dev",
  "ipv6": "fd77:7777:5010::1337:3c:d00d:2",
  "hex_id": "2",
  "port": 25565,
  "start_mode": "ondemand",
  "idle_timeout_minutes": 20,
  "type": "paper",
  "mc_version": "1.21.4",
  "jar_file": "server_26.3.jar",
  "java_bin": "/usr/lib/jvm/default/bin/java",
  "memory_min": "8G",
  "memory_max": "8G",
  "seed": "4900633019313953717",
  "admins": [],
  "created_at": "2026-10-10T18:03:46-04:00"
}

6.2 Resource Management & Server Lifecycle Modes

Because each active Minecraft JVM allocates $8\text{--}20\text{ GiB}$ of pinned heap memory (-Xms = -Xmx with +AlwaysPreTouch), running all $25+$ worlds in /data/minecraft simultaneously is impossible. Each server is assigned one of three lifecycle modes:

1. manual (Cold / Archived):
   • minecraft@<slug>.service is disabled and stopped ($0\text{ GiB}$ RAM).
   • Only starts when explicitly clicked in the Web UI.
   • When stopped, HAProxy returns <name> is currently offline. Start at mc.drheck.dev.
2. ondemand (Wake-on-Join + Idle Auto-Stop):
   • Stopped by default ($0\text{ GiB}$ RAM).
   • Automatically started when a player clicks Join Server in Minecraft (intercepted by HAProxy Lua $\longrightarrow$ mc-manager).
   • Automatically stopped (save-all $\longrightarrow$ stop) once $0$ players have been online continuously for $T_{\text{idle}}$ minutes (default $20\text{ min}$).
3. always (Pinned Production):
   • minecraft@<slug>.service is enabled and active across host reboots (systemctl enable --now).
   • Used for primary worlds that should remain online $24/7$ regardless of player count.

6.3 HAProxy On-Demand Wake-on-Join & Live Status Ping Architecture

The Minecraft protocol sends a Handshake packet (0x00) at the start of every TCP connection containing a Next State VarInt:

• $\text{Next State} = 1$ (Status Ping): Sent when a client refreshes their Multiplayer Server List.
• $\text{Next State} = 2$ (Login Join): Sent only when a player clicks Join Server.

/etc/haproxy/minecraft.lua extracts both txn.mc_host and txn.mc_state and delegates status pings and offline joins to mc-manager (http://127.0.0.1:8095/internal/haproxy):

$$\text{Client Packet } (\texttt{0x00}) \longrightarrow \begin{cases} \text{state} = 1 \text{ (Status Ping)} & \longrightarrow \text{Return live JSON MOTD + } \texttt{server-icon.png} \text{ from } \texttt{mc-manager} \text{ without waking} \\ \text{state} = 2 \text{ (Login Join)} & \longrightarrow \text{If } \texttt{ONLINE}\text{: TCP splice to backend; if } \texttt{ondemand}\text{: wake server + return countdown} \end{cases}$$

State Machine for Managed Worlds

Idle Shutdown Timer

For any running server in ondemand mode, mc-manager tracks the time since the last player disconnected ($N_{\text{players}} = 0$). When:

$$t_{\text{empty}} \ge T_{\text{idle}} \quad (\text{default } 20\text{ min})$$

mc-manager issues save-all and stop via the /run/mc-manager/<slug>.sock PTY socket and stops minecraft@<slug>.service, freeing the JVM heap until the next join request.

6.4 Web Control Plane (https://mc.drheck.dev)

The web frontend is served over HTTPS behind Nginx + Authentik ForwardAuth and provides two primary workspaces designed with a clean, hardware-ops dark interface:

1. Existing Servers Dashboard & Live PTY Console

• Server Sidebar & Status Header:
  • Displays every registered server with its 64×64 pixel icon, live state badge (ONLINE, STANDBY, OFFLINE), endpoint (<slug>.drheck.dev), IPv6 address, heap allocation, and lifecycle mode (On-Demand, Always On, Manual).
  • One-Click Controls: Start Server, Restart, Stop, and + Provision Network / DNS (if not yet allocated).
• Live Server Console (mc-runner WebSocket Stream):
  • Connects via WebSocket (/api/servers/<slug>/console/ws) to /run/mc-manager/<slug>.sock, streaming the 1,000-line PTY ring buffer and real-time server stdout/stderr lines.
  • Allows admins to send console commands (say, op, whitelist, time set, gamemode, /give, etc.) directly to the server's stdin (leading / is automatically stripped because the server console expects bare commands).
• Configuration, Text/MOTD Studio, Icon Studio, Whitelist & Operators Panels:
  • Edit Display Name, MOTD, Start Mode, Idle Timeout, Min/Max Heap, Jar File, Gamemode, Difficulty, Max Players, View Distance, Level Seed, server-icon.png, whitelist.json, and ops.json.

2. Minecraft Text, MOTD, Color Gradient & 8-Bit Pixel Icon Studio

Built directly into both the + New World screen and the Configuration panel of every existing server:

• Unicode Font Converter (Copy/Paste Safe):
  • Converts text into Minecraft Java Edition font variants without resource packs: Small Caps (ꜱᴍᴘ), Gothic / Fraktur (𝔖𝔲𝔯𝔳𝔦𝔳𝔞𝔩), Double-Struck (𝕊𝕦𝕣𝕧𝕚𝕧𝕒𝕝), Full-Width (ＳＭＰ), and Monospace.
  • Includes one-click Java-Safe Decorative Symbols & Borders: ⚔, ◆, ★, ⚡, 👑, ☠, ✦, ❖, », «, and ⚔ ... ⚔.
• § Color Gradient & Formatting Code Builder:
  • Interpolates any two RGB colors (Gradient Start $\longrightarrow$ Gradient End) across the input string and maps each character to the nearest native Minecraft color code (§0–§f), combined with optional §l (Bold), §o (Italic), §n (Underline), §m (Strikethrough), or §k (Obfuscated).
  • Can be applied with one click to either MOTD (server.properties) or Display Name (server.json), with a real-time Minecraft Multiplayer Server List Preview rendering § codes and the 64×64 icon side-by-side.
• 8-Bit Pixel Icon & Badge Generator (64×64 server-icon.png):
  • Generates crisp 64×64 pixel-art server icons in the browser using 6 Minecraft material themes (Stone, Dirt & Grass, Diamond, Glowstone, Nether, Enchanted Glint), 7 pixel-art stamps (Sword, Pickaxe, Creeper, Crown, Heart, Star, Pokéball), and 1–3 character 8-bit bitmap text with 3D drop shadows, or accepts any custom uploaded PNG/JPG/WebP image (auto-cropped and resampled to 64×64).

3. Interactive Seed Preview Studio (cubiomes Native Renderer)

• Uses /usr/local/bin/mc-seed-render (compiled against cubiomes) on ul to render a 2D biome map ($\pm 2048$ blocks around $(0,0)$) and locate nearest structures (Village, Ancient City, Mansion, Monument, Outpost, Stronghold, Ruined Portal) in $< 50\text{ ms}$ per seed.
• Supports Roll Random Seed and interactive biome legend inspection prior to provisioning a new world.

6.5 Authentik Gate, RBAC & Automatic /op (ops.json) Synchronization

Access to https://mc.drheck.dev is gated at the Nginx perimeter via Authentik ForwardAuth (X-Authentik-Username), and mc-manager maps authenticated identities via /data/minecraft/.manager/users.json:

$$\text{Authentik SSO } (\texttt{auth.drheck.dev}) \longrightarrow \text{Nginx ForwardAuth } (\texttt{X-Authentik-Username}) \longrightarrow \texttt{mc-manager} \text{ RBAC + } \texttt{ops.json} \text{ Sync}$$

• Global Admins (global_admin: true, e.g., luke): Full access to create servers, provision network/DNS, manage the Users & Operators Registry (with live Mojang API username $\longrightarrow$ UUID lookup), and administer all worlds.
• Per-Server Admins (server.json admins): Full control to start/stop/restart, access the live console, and edit configuration/whitelist/icon on their assigned worlds.
• Automatic ops.json Synchronization: Adding a user as a Global Admin or Server Admin automatically syncs their Mojang UUID and username into ops.json (Level 4 operator with bypassesPlayerLimit: true).

6.6 Server-Side Quality-of-Life (QoL) Datapack Library & Non-Agentic Modrinth Updater

All server-side Quality-of-Life (QoL), building, and world-generation datapacks (world/datapacks/*.zip) run 100% on the server so players connect with a standard Vanilla Minecraft client without installing any client-side mod loader.

Curated Server-Side Datapack Library (/data/minecraft/datapacks/)

Both the + Create New Server studio and every server's QoL Mods & Datapacks tab in https://mc.drheck.dev include a 16-pack verified library plus live Modrinth v2 search:

Non-Agentic Deterministic Update Pipeline (Web UI, CLI & Weekly systemd Timer)

Datapacks are updated deterministically without any AI agent involvement by querying the Modrinth v2 REST API (/v2/version_file/<sha1> and /v2/project/<slug>/version?loaders=["datapack"]), verifying the downloaded archive against Modrinth's published SHA-1 digest, replacing the old .zip atomically in world/datapacks/, and issuing reload over /tmp/mc-runner-<slug>.sock if the server is online:

$$\text{On-Disk }\texttt{.zip}\text{ SHA-1} \longrightarrow \texttt{api.modrinth.com/v2} \longrightarrow \text{SHA-1 Verified Download} \longrightarrow \text{Atomic Swap + }\texttt{/reload}$$

1. Web UI (https://mc.drheck.dev): Open any server $\longrightarrow$ QoL Mods & Datapacks tab $\longrightarrow$ click ↻ Check Modrinth Updates or ⬆ Update All Installed Datapacks.
2. Manual CLI Check / Update:

   # Check all servers for available Modrinth datapack updates (read-only):
   /usr/local/bin/mc-manager -check-datapacks
   
   # Download, SHA-1 verify, and apply all available Modrinth datapack updates across all servers:
   /usr/local/bin/mc-manager -update-datapacks
   

3. Automated Weekly systemd Timer (mc-datapack-update.timer):
   • /etc/systemd/system/mc-datapack-update.timer triggers /etc/systemd/system/mc-datapack-update.service every Sunday at 04:15 EDT, keeping all server datapacks and /data/minecraft/datapacks/ up to date automatically.

6.7 Server Binary Repository (/data/minecraft/jars/) & Non-Agentic Upstream Version Catalog

mc-manager maintains a centralized, metadata-indexed Server Binary Repository in /data/minecraft/jars/ backed by two JSON manifests:

1. /data/minecraft/jars/index.json (Local Binary Inventory & Introspected JAR Metadata):
   • Every .jar in /data/minecraft/jars/ (and every managed server's active jar_file) is automatically inspected by reading the embedded version.json and META-INF/MANIFEST.MF inside the ZIP archive:
     • flavor: paper, vanilla, folia, fabric, or forge
     • mc_version: Exact Minecraft release version (e.g., 26.3, 26.2, 1.21.11, 1.20.1)
     • build: PaperMC / Folia build number (e.g., 170 for paper-26.3-170.jar)
     • protocol_version: Wire protocol version (e.g., 777 for 26.3, 776 for 26.2)
     • data_pack_format: Datapack major format (e.g., 121 for 26.3)
     • java_version: Required Java major version (e.g., 25 for 26.2/26.3, 21 for 1.21.x, 17 for 1.18–1.20)
     • sha256: Full SHA-256 digest of the .jar file
2. /data/minecraft/jars/upstream_catalog.json (Upstream Supported Versions & Latest Builds):
   • Synchronized deterministically (without any AI agent) against the four official upstream REST APIs:
     • PaperMC Fill v3 API (https://fill.papermc.io/v3/projects/paper and /versions/<ver>/builds with SHA-256 verification)
     • Folia Fill v3 API (https://fill.papermc.io/v3/projects/folia and /versions/<ver>/builds with SHA-256 verification)
     • Mojang Official Piston Meta v2 (https://piston-meta.mojang.com/mc/game/version_manifest_v2.json with SHA-1 verification)
     • FabricMC Meta v2 (https://meta.fabricmc.net/v2/versions for game versions, loader 0.19.5, and installer 1.1.2)

Non-Agentic Binary & Version Sync Workflow (Web UI, CLI & Weekly systemd Timer)

1. Web UI (https://mc.drheck.dev):
   • Click Binary Repo & Versions in the left sidebar to view all indexed binaries in /data/minecraft/jars/, sync upstream version lists (26.3 first), download & verify any PaperMC, Vanilla, Fabric, or Folia release into /data/minecraft/jars/, or click ⬆ Update All Cached & Server Binaries.
   • In any server's Config, Seed & Text Studio tab, select any binary from the Repository Binary dropdown or click ⬆ Upgrade JAR to switch or upgrade the server in one click.
2. Standalone CLI Commands:

   # Sync upstream version catalog and check all repository & server binaries:
   /usr/local/bin/mc-manager -check-binaries
   
   # Fetch & SHA-256/SHA-1 verify a specific upstream server binary into /data/minecraft/jars/:
   /usr/local/bin/mc-manager -fetch-jar paper:26.3
   /usr/local/bin/mc-manager -fetch-jar vanilla:26.3
   
   # Automatically download newer Paper/Folia builds and update servers in-place:
   /usr/local/bin/mc-manager -update-binaries
   

3. Automated Weekly systemd Timer (mc-datapack-update.timer):
   • Runs /usr/local/bin/mc-manager -update-binaries -update-datapacks every Sunday at 04:15 EDT.