Minecraft Worlds

Quickstart: Bring a World Up

1. AllocateCreate IP,via SNIWeb Route,Control Plane (https://mc.drheck.dev) or CLI (ipctl):
2. Web UI (Recommended): Open https://mc.drheck.dev, click + New World, style the world name/MOTD and DNS:64×64 icon, preview/reroll the world seed with the live 2D biome map, and click Create & Provision World.

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

(Or /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,routing in /etc/haproxy/conf.d/minecraft_backends.cfg and /etc/haproxy/minecraft_hosts.map, adds <name>.drheck.dev into Unbound/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)deSEC.io).

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 stock vanilla Minecraft,with online-mode=true, listening on standard port 25565) on their dedicated ULA IPv6 address).

Start the server: LaunchStart yourvia Minecrafthttps://mc.drheck.dev server(Start onbutton UL.or Itautomatic bindsOn-Demand towake-on-join) itsor dedicatedsudo IPv6systemctl address.start minecraft@<slug>.service.

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

Quickstart: Take a World Down

1. Stop the backend server: RunClick Stop in https://mc.drheck.dev, send stop in the Minecraftlive serverweb consoleconsole, or terminaterun itssudo process.systemctl stop minecraft@<slug>.service.

2. What Players See When Offline:Offline or Standby (On-Demand): HAProxy monitorsintercepts backendall healthMultiplayer checks.Server IfList thepings server($\text{state} process= is1$) stopped:and offline/standby Login joins ($\text{state} = 2$) via /etc/haproxy/minecraft.lua and mc-manager:

   • In the Multiplayer Server List:List (state = 1): TheReturns pingthe server's configured custom MOTD displays:and 64×64 [Serverserver-icon.png Name](favicon) isimmediately, currentlywith offline.version Pingstatus Lukebadge Standby (Join to Wake) (for ondemand servers) or Offline (for manual servers).
   • When Clicking "Join Server" (state = 2): The
     client
   • ondemand immediatelyStandby: Automatically triggers minecraft@<slug>.service to boot and displays a gold countdown screen (Waking up <Server>... Ready in ~20s!).
3. manual Offline: Immediately disconnects with a clean red Minecraftscreen disconnect screen: "[(<Server Name]> is currently offline. PingStart Luke"at (Nomc.drheck.dev).

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 & OfflineLive FallbackPing Injection (HAProxy)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 connectionhandshake state (txn.mc_state: 1 = Status vsPing, Login)2 = Login Join).

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

• If the backend server is UP: ItHAProxy splices the raw TCP stream directly to that server's dedicated internal IPv6 address on port [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: HAProxy immediately handles the stream with Lua applet lua.mc_offline sends JOIN <slug> to mc-manager, which craftswakes ondemand servers automatically and sendsreturns a validformatted Minecraft protocol packet:
• Status Ping: JSON MOTD with red text: <name> is currently offline. Ping Luke

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.
• Security:Active Managed Worlds:

4. Web Map (BlueMap) & Authentik Gated HTTPS

Interactive 3D web mapping for Minecraft 26.3 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.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

TheTo toolprevent 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 inat /home/luke/bin/ipctl) automatesoperates theexclusively entireon lifecycle: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):

Backups & Disaster Recovery

TheBoth the HAProxy router configurations, Lua scripts, mapping tables, network configurations,layer and the ipctlmc-manager toolcontrol plane (including all external network, proxy, and DNS mirror files) are integrated into the automated backup infrastructure:/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/.

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

DesignProduction Goal:Control Plane: Provide aThe unified web control plane (at https://mc.drheck.dev, gated(bound byto Authentik)[fd77:7777:5010::1337:f1ac:d00d:3c00]:8095 behind Nginx and daemonAuthentik thatForwardAuth) formalizesmanages what aall Minecraft server isworlds 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 interactiveintegrated seed-previewSeed Preview Studio and modpackText, studioMOTD, whenColor creatingGradient new& worlds.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$$

{
  "name": "Poke Lovers",
  "slug": "pokelovers"desertworld",
  "directory"display_name": "/data/minecraft/poke⚔ lovers"𝔇𝔢𝔰𝔢𝔯𝔱 𝔚𝔬𝔯𝔩𝔡 ⚔",
  "dir_name": "desertworld",
  "domain": "pokelovers.desertworld.drheck.dev",
  "bind_ipv6"ipv6": "fd77:7777:5010::1337:3c:d00d:1"2",
  "game_port"hex_id": "2",
  "port": 25565,
  "rcon_port": 25575,
  "loader"start_mode": "vanilla"ondemand",
  "idle_timeout_minutes": 20,
  "type": "paper",
  "mc_version": "26.3"1.21.4",
  "jar_file": "server_26.3.jar",
  "java_bin": "/usr/lib/jvm/java-26-openjdk/default/bin/java",
  "memory_min_gb"memory_min": 20,"8G",
  "memory_max_gb"memory_max": 20,
  "use_aikars_flags": true,
  "modpack": null,8G",
  "seed": "-41829401829401",
  "lifecycle_mode": "ondemand",
  "idle_shutdown_minutes": 20,
  "bluemap_enabled": true,
  "bluemap_port": 8100,
  "owner": "luke"4900633019313953717",
  "admins": ["luke", "ikura"],
  "sync_ingame_ops"created_at": true"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:returns <name> is currently offline. PingStart Lukeat 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)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 (or when internet bots scan port 25565).List.
• $\text{Next State} = 2$ (Login Join): Sent only when a player clicks Join Server.

/etc/haproxy/minecraft.lua already extracts both txn.mc_host and txn.mc_state. Extendingand delegates status pings and offline joins to mc_offlinemc-manager enables zero-overhead on-demand activation without waking servers on server-list pings:(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{Sleeping /from Starting} / Offline})\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{: trigger } \texttt{mc-manager} \text{ wake socketserver + return countdown packet}countdown} \end{cases}$$

State Machine for ondemandManaged 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$) after an initial post-boot grace period ($T_{\text{grace}} = 5\text{ min}$ so players have plenty of time to connect after waking the server). When:

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

mc-manager issues save-all and stop via RCONthe /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:workspaces designed with a clean, hardware-ops dark interface:

1. Existing Servers Dashboard & Live PTY Console

• Server FleetSidebar Cards& Status Header:
  • Displays every registered server with its 64×64 pixel icon, live state badge (ONLINE, STARTING, SLEEPING (ON-DEMAND)STANDBY, OFFLINE), online player list, RAM/CPU usage, Minecraft version, loader typeendpoint (Paper, Vanilla, Fabric, Forge), and <slug>.drheck.dev), endpoint.IPv6 address, heap allocation, and lifecycle mode (On-Demand, Always On, Manual).
  • One-Click Controls: Start Server, Restart, Stop, Restart, and a dropdown to switch the server between Manual, On-Demand, and Always+ On.
  Provision
• Live Console & Config Drawer: WebSocket log stream (journalctl -u minecraft@<slug>.service -f) with RCON command input, visual server.propertiesNetwork / whitelist.jsonDNS /(if ops.jsonnot editor,yet and BlueMap 3D map toggle.allocated).

• ScansConnects via WebSocket (/api/servers/<slug>/console/ws) to /data/minecraft/*run/mc-manager/<slug>.sock, forstreaming directoriesthe without1,000-line aPTY server.jsonring manifestbuffer and real-time server stdout/stderr lines.

2. CreateMinecraft NewText, ServerMOTD, Color Gradient & 8-Bit Pixel Icon Studio

CreatingBuilt adirectly newinto world follows a 3-step guided workflow inboth the Web+ UI:New World screen and the Configuration panel of every existing server:

1. • StepUnicode 1Font —Converter Identity,(Copy/Paste Networking & Resource ProfileSafe):
     • DisplayConverts Nametext &into Subdomain:Minecraft EnteringJava Edition font variants without resource packs: CreateSmall WorldCaps (ꜱᴍᴘ) auto-suggests slug, createworldGothic / Fraktur (𝔖𝔲𝔯𝔳𝔦𝔳𝔞𝔩), createworld.drheck.devDouble-Struck (𝕊𝕦𝕣𝕧𝕚𝕧𝕒𝕝)), Full-Width (ＳＭＰ), and Monospace.
     • Includes one-click LifecycleJava-Safe PolicyDecorative Symbols & Borders: Select On-Demand⚔ (default), Always On◆, or Manual★, plus heap size (4 GiB⚡ –, 24👑, GiB☠), ✦, ❖, », «, and optional⚔ BlueMap... 3D Web Map provisioning.⚔.
   • Step§ 2Color — Server BinaryGradient & CustomFormatting ModpacksCode 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 EngineList SelectorPreview rendering § codes and the 64×64 icon side-by-side.

• PaperGenerates /crisp Purpur64×64 /pixel-art Vanillaserver / Fabric / NeoForge / Forge: Queries live upstream release APIs (or local cached jarsicons in /data/minecraft/jars/) so you can pick the exactbrowser using 6 Minecraft versionmaterial and build from a dropdown.

3. Interactive Seed Preview & Reroll Studio:

• Uses a/usr/local/bin/mc-seed-render headless(compiled nativeagainst cubiomes C renderer) on ul to generaterender a high-resolution 2D biome colour 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, overlaid with exact structure icons (Spawn point, Villages, Ancient Cities, Woodland Mansions, Ocean Monuments, Pillager Outposts, Strongholds, and Nether Fortresses/Bastions).seed.
• Lets you clickSupports 🎲 Roll Random Seed repeatedlyand untilinteractive youbiome spotlegend aninspection idealprior spawnto island,provisioning continent,a ornew structure cluster, or bookmark candidate seeds side-by-side before creating the server.world.

6.5 Authentik Gate, OIDC Role-Based Access Control (RBAC)RBAC & In-GameAutomatic /op Sync(ops.json) Synchronization

Access to https://mc.drheck.dev is protected by a two-layer Authentik security model that gates the entire web interfacegated at the Nginx perimeter while using nativevia OpenIDAuthentik ConnectForwardAuth (OAuth2ProviderX-Authentik-Username) claims to grant granular Server Admin privileges both in the web UI, and insidemc-manager themaps Minecraftauthenticated serversidentities themselves.via /data/minecraft/.manager/users.json:

$$\text{Authentik SSO } (\texttt{auth.drheck.dev}) \longrightarrow \begin{cases} \text{Layer 1: Nginx ForwardAuth } (\texttt{ProxyProvider}X-Authentik-Username}) & \longrightarrow \text{Blocks unauthenticated requests at perimeter} \\texttt{mc-manager} \text{Layer 2: OIDC JWTRBAC + Scopes } (\texttt{OAuth2Provider}) & \longrightarrow \text{Maps } \texttt{groups}ops.json} \text{ and } \texttt{entitlements} \text{ to RBAC + RCON } \texttt{/op} \end{cases}Sync}$$

1. Authentik OIDC Scopes & Claim Evaluation

mc-manager authenticates users via OIDC Authorization Code Flow with PKCE against https://auth.drheck.dev/application/o/mc/ (verifying RS256 JWT tokens against https://auth.drheck.dev/application/o/mc/jwks/) and inspects three identity sources on every HTTP request and WebSocket frame:

• profileGlobal ScopeAdmins (groupsglobal_admin: true claim): Reads Authentik group memberships (["mc_admins", "mc_server_admins", "ul_ssh", ...]).

2. Three-Tier Privilege Matrix

3. Automatic OIDC-to-Minecraft /op (ops.json) Synchronization

Each authenticated user can linksyncs their Minecraft Java Edition username once in the mc.drheck.dev profile bar (stored in Authentik user attributes user.attributes.mc_username and resolved to an immutable Mojang UUID via https://api.mojang.com/users/profiles/minecraft/<username>):

6.6 End-to-End Automated Provisioning Pipeline

When Create Server is clicked in the Web UI, the backend executes the following atomic pipeline: