ulicraft-server-v1/CLAUDE.md

Ulicraft Server — Project Context

Self-hosted modded Minecraft (NeoForge 1.21.1) with self-hosted auth/skins (Drasl), a distribution-fed modpack, avatar rendering, a guest landing page, and uptime monitoring. Public, internet-present deployment behind the host's nginx + TLS.

plan/ is the source of truth for the design. Start at plan/00-overview.md. This file is a fast orientation + the durable decisions/gotchas; when it disagrees with plan/ or the code, those win.

Goals & Constraints

• Players: 4–10 friends
• Modpack vibe: Kitchen-sink (tech + magic + exploration + QoL)
• Pack approach: Manually curated (~50–100 mods), NOT a forked existing pack
• Minecraft version: 1.21.1, NeoForge (not classic Forge)
• Auth/skins: Drasl (Yggdrasil-compatible), password login — no OIDC
• DNS: handled OUTSIDE this repo; point ${BASE_DOMAIN} + subdomains at the host
• Persistence horizon: long-term service, not disposable

Architecture

One unified docker-compose.yml. The host's own nginx terminates TLS (Let's Encrypt) and reverse-proxies every vhost to caddy (published localhost-only) by Host header. caddy is the internal router; containers reach the stack's own names via caddy's mcnet aliases (auth., pack.).

Internet ── host nginx (TLS, LE certs, HSTS) ──► caddy (127.0.0.1:8880)
                                                   │ routes by Host:
   ${BASE_DOMAIN}        ─► /srv/www landing + /launcher/ downloads
   auth.${BASE_DOMAIN}   ─► drasl        (Yggdrasil API + web UI)
   avatar.${BASE_DOMAIN} ─► nmsr         (skin/avatar renderer, Drasl-backed)
   status.${BASE_DOMAIN} ─► uptime-kuma  (status page + monitors)
   distribution.${BASE}  ─► static site from ANOTHER repo (DISTRIBUTION_WEB_ROOT)

minecraft :25565 (+ 24454/udp Simple Voice Chat)
   └ ONLINE_MODE=false, -javaagent authlib-injector → http://auth.${BASE_DOMAIN}/authlib-injector
   └ mods from ./server-mods volume (/mods, REMOVE_OLD_MODS) — see plan/04-mods.md
mc-backup ── RCON → minecraft (6h interval, prune 14d, world-only)

Bring-up: render configs → sync server mods → build landing → fetch launcher → docker compose up -d --build. See plan/12-build-order.md and plan/14-deploy.md. Deploy to prod host cochi via the deploy skill.

Key Decisions

• NeoForge over Forge — the 1.21.x kitchen-sink ecosystem is overwhelmingly NeoForge; the Forge team migrated. itzg/minecraft-server via TYPE=NEOFORGE.
• Drasl over Ely.by / vanilla offline — self-hosted Go service, Yggdrasil drop-in, skins + capes, actively maintained. Run with password login (no OIDC/Keycloak in this stack).
• Manual curation (user choice, flagged expensive) — if it gets painful, fork-and-trim Leaking Kitchen Sink is still on the table (closest vibe match).
• itzg/minecraft-server base image — de-facto standard, auto-installs NeoForge.
• Distribution-fed mod volume (replaced packwiz) — the modset's source of truth is the HeliosLauncher distribution repo ($DISTRIBUTION_WEB_ROOT). Clients install the full set via distribution.json. The SERVER loads a filtered subset (both/server) from a mounted ./server-mods volume (REMOVE_OLD_MODS=TRUE). See plan/04-mods.md.

Critical Gotchas

Minecraft 1.21+ secure profile

• Server: ENFORCE_SECURE_PROFILE=FALSE (enforce-secure-profile=false)
• Drasl: SignPublicKeys = false
• Linked. Drasl docs: "Mixed authentication does not work with SignPublicKeys = true on Minecraft 1.21+."

authlib-injector JVM agent

• Syntax: -javaagent:/extras/authlib-injector.jar=<yggdrasil-api-url>
• URL after = is the API root = <BaseURL>/authlib-injector. For this stack: http://auth.${BASE_DOMAIN}/authlib-injector (internal, over mcnet).
• Must match between server and client (clients use the public https://auth.${BASE_DOMAIN}/authlib-injector), else session validation fails silently with "Invalid session".
• Releases: https://github.com/yushijinhun/authlib-injector — jar lives in runtime/ (mounted at /extras/authlib-injector.jar).

NeoForge version pinning

Mods are picky about exact minor versions. Compose pins NEOFORGE_VERSION: "21.1.233" — must match the distribution's NeoForge (distribution.json), since mods are built against it (e.g. ferritecore≥218, farmersdelight≥219). Verify against https://projects.neoforged.net/neoforged/neoforge before deploying. Never "latest" for a stable server.

Mod source + server filtering

The full modset lives in the distribution repo ($DISTRIBUTION_WEB_ROOT/servers/ ulicraft-1.21.1/forgemods/required/*.jar), managed by Nebula. Clients get everything via distribution.json. The server runs a filtered subset: tooling/classify-mods.py reads each jar's neoforge.mods.toml with tomllib and seeds mods-sides.json (client|server|both, default both), then tooling/sync-server-mods.sh copies the both/server jars into ./server-mods (mounted at /mods). Hard client-only mods (sodium/iris) classify as client automatically; cosmetic-client mods that declare BOTH stay both until you hand-edit mods-sides.json to client. No Modrinth/packwiz, no network at classify/sync time. See plan/04-mods.md.

Memory sizing

~50–100 mods, 8 players, 1.21.1: INIT_MEMORY: 4G, MAX_MEMORY: 10G, USE_AIKAR_FLAGS: TRUE.

Config (.env)

BASE_DOMAIN, RCON_PASSWORD, CADDY_HTTP_PORT/CADDY_HTTP_BIND, DISTRIBUTION_WEB_ROOT (source of the modset + caddy distribution. mount), the Let's Encrypt block (LE_EMAIL, LE_SUBDOMAINS, OVH_*). Rendered configs (drasl, nmsr) come from *.tmpl via tooling/render-config.sh (substitutes ${BASE_DOMAIN} only). Server mods are synced (not rendered) by tooling/sync-server-mods.sh.

Client Distribution (guests)

Launcher: FjordLauncherUnlocked (Prism fork, first-class authlib-injector), mirrored at apex /launcher/. Per guest:

1. Download from https://${BASE_DOMAIN} → /launcher/.
2. Add an authlib-injector account, URL https://auth.${BASE_DOMAIN}/authlib-injector (register/login at https://auth.${BASE_DOMAIN}).
3. The launcher installs the modpack from the distribution (distribution.json). (NOTE: packwiz/pack. removed — the landing join step still references a packwiz URL and needs reworking around the launcher/distribution flow.)
4. Connect to ${BASE_DOMAIN} (:25565).

Open / Pending Work

Roadmap — mod migration follow-ups (post packwiz→04-mods)

• Curate mods-sides.json cosmetic-client mods. tomllib auto-flagged 11 hard client-only mods; the other 65 default both, including client-cosmetic ones (BetterF3, entityculling, MouseTweaks, ponderjs, fancymenu, drippy, melody, welcomescreen, Searchables, JustEnoughResources, TravelersTitles, yeetus…) that load harmlessly on the server but waste RAM. Hand-edit them to client so sync-server-mods.sh drops them from ./server-mods. (Also review appleskin, flagged client — flip to both if server-side food data wanted.)

• Rework the landing join flow off packwiz. pack. vhost is gone; site.ts packwizUrl is a dead-URL placeholder (kept w/ TODO so the build passes) and i18n/ui.ts join steps (all 3 langs) still tell guests to import pack.toml. Redesign step 3 around the HeliosLauncher/distribution.json install flow. See plan/04-mods.md + site.ts TODO.

• Mod shortlist for the kitchen-sink pack: Performance (Embeddium, FerriteCore, ModernFix), Tech (Mekanism, Create, IE, AE2), Magic (Ars Nouveau, Botania, Iron's Spells), Storage (Sophisticated, Functional), Exploration (YUNG's, Repurposed Structures), QoL (JEI, Jade, IPN, AppleSkin), World gen (Tectonic, Terralith — verify NeoForge 1.21.1), Compat (Polymorph), Map (Xaero), Voice (Simple Voice Chat — 24454/udp already in compose).

• Server-side perf mods (C2ME, etc.).

• Verify NeoForge version against current stable before first deploy.

• Bootstrap Drasl admin account.

Reference URLs

• Drasl: https://github.com/unmojang/drasl — config docs: https://github.com/unmojang/drasl/blob/master/doc/configuration.md
• authlib-injector: https://github.com/yushijinhun/authlib-injector
• itzg/minecraft-server: https://github.com/itzg/docker-minecraft-server (NeoForge: …/docs/types-and-platforms/server-types/forge.md)
• itzg/mc-backup: https://github.com/itzg/docker-mc-backup
• NeoForge versions: https://projects.neoforged.net/neoforged/neoforge
• NMSR: https://github.com/NickAcPT/nmsr-rs
• Uptime Kuma: https://github.com/louislam/uptime-kuma
• FjordLauncherUnlocked: https://github.com/hero-persson/FjordLauncherUnlocked
• Reference packs (inspiration, NOT forking): ATM10, Leaking Kitchen Sink.

Communication Preferences (carry-over)

• Concise and direct; diagnose + resolve without demanding repro steps.
• Prefer iterative single-change updates over large rewrites.
• Cautious scripts that halt on ambiguity rather than proceeding silently.
• Avoid over-engineering when a simple answer suffices.
• Spanish or English both fine.