ulicraft-server-v1/plan/00-overview.md

Ulicraft Server — Plan Overview

Self-hosted modded Minecraft stack — a single Docker Compose file holds the entire thing, fronted by the host's own nginx (Let's Encrypt TLS) and a caddy internal router. Built for a LAN party but runs as a persistent homelab service. Assumes the internet is present.

Single source of configuration

Everything is driven by one env var in .env:

BASE_DOMAIN=ulicraft.net      # all services are subdomains of this

render-config.sh substitutes ${BASE_DOMAIN} into the templates (plus the derived REGISTRATION_* and FILES_* values — see 20-files.md). DNS is not this repo's concern: point ${BASE_DOMAIN} and all subdomains (auth. avatar. status. files. distribution. www.) at the host running nginx; that is configured outside this repo.

Subdomain / ingress map

ulicraft.net               → nginx → caddy → landing page (/srv/www) + /launcher/
auth.ulicraft.net          → nginx → caddy → drasl:25585   (auth web UI + Yggdrasil API)
avatar.ulicraft.net        → nginx → caddy → nmsr:8080      (skin/avatar renderer)
status.ulicraft.net        → nginx → caddy → uptime-kuma:3001 (status page)
files.ulicraft.net         → nginx → caddy → filestash:8334 (player file share, shared login)
distribution.ulicraft.net  → nginx → caddy → /srv/distribution (static, another repo)
mc.ulicraft.net:25565      → minecraft                      (raw MC protocol, not HTTP)

The host's own nginx is the only public ingress: it terminates TLS with Let's Encrypt certs and reverse-proxies every vhost to caddy by Host header. caddy is published on a localhost-only port (CADDY_HTTP_BIND=127.0.0.1, CADDY_HTTP_PORT=8880) and acts as the internal router. drasl, nmsr and uptime-kuma have no host ports — they are reached only through caddy.

Internal resolution trick

Containers use the Docker resolver. caddy gets network aliases so the stack resolves its own subdomains internally:

caddy:
  networks:
    mcnet:
      aliases: [ "auth.${BASE_DOMAIN}" ]

Result: http://auth.ulicraft.net/authlib-injector resolves identically inside the stack (minecraft → caddy) as the public name does outside it (client → nginx → caddy).

HTTPS variant (extra_hosts: host-gateway)

The caddy alias only serves http on mcnet (port 80). Once the stack moved to https URLs (drasl BaseURL; the authlib-injector agent must match the client's https endpoint), the internal http alias is no longer enough — the container needs to reach a TLS terminator holding a valid cert.

Caddy does not terminate TLS internally; the host's nginx does (on 0.0.0.0:443). So pin the public name to the host in the service, not to caddy:

minecraft:
  extra_hosts:
    - "auth.${BASE_DOMAIN}:host-gateway"

/etc/hosts (extra_hosts) wins over the Docker resolver, so the container reaches the host's nginx (valid LE cert) → caddy → service. This is required because containers do not inherit the host's /etc/hosts — on cochi the host resolves auth. to the public IP, but inside a container the LAN resolver returns a dead address (192.168.0.3:443, connection refused), which crash-loops session validation on boot. host-gateway sidesteps DNS entirely.

Build / run flow

PREP (run once, online):
  1. render configs                 → tooling/render-config.sh  (08-tooling.md)
  2. build landing page             → cd landing && pnpm run build → www/ (09-landing.md)
  3. download launcher releases     → tooling/fetch-launcher.sh (06-launcher.md)
  4. sync server mods               → tooling/sync-server-mods.sh (04-mods.md)
  5. (TLS) issue Let's Encrypt certs → tooling/issue-letsencrypt.sh (15-letsencrypt.md)
  6. (ingress) render+install nginx → tooling/render-nginx.sh --install (15-letsencrypt.md)

UP:
  docker compose up -d --build

Bring-up is a single command. There are no run modes and no override compose files — one docker-compose.yml holds drasl, minecraft, mc-backup, caddy, nmsr, mc-status, uptime-kuma and filestash.

Why each hard call was made

• No OIDC/Keycloak (for now) — drasl password login. Keycloak left out of this stack's scope. Re-add later if desired.
• Distribution-fed mods — the modset's source of truth is the HeliosLauncher distribution repo; clients install the full set, the server loads a filtered both/server subset from ./server-mods. See 04-mods.md.
• Fjord launcher has authlib-injector built in → no manual JVM agent on clients.
• host nginx in front of caddy — real Let's Encrypt certs (JVM trusts them with no CA import) and a single public TLS terminator; caddy stays an internal Host-routed multiplexer for the stack's own services.

Target folder layout

.
├── docker-compose.yml           # the entire stack (no overrides)
├── .env / .env.example          # BASE_DOMAIN, RCON_PASSWORD, CADDY_*, LE block
├── caddy/conf.d/                # per-vhost snippets (00-core, 10-static, …)
├── nginx/ulicraft-caddy.conf.tmpl  # host nginx → caddy template (TLS terminator)
├── certs/<name>/{cert,key}.pem  # Let's Encrypt output (gitignored)
├── drasl/config/
│   ├── config.toml.tmpl         # render-config.sh source
│   └── config.toml              # generated (gitignored)
├── nmsr/                        # avatar renderer config + Dockerfile context
├── filestash/
│   ├── config.json.tmpl         # render-config.sh source (files. share)
│   └── config.json              # generated, mounted :ro (gitignored — holds hashes)
├── docker/nmsr/                 # nmsr image build context
├── server-mods/                 # filtered server modset (synced, gitignored)
├── launcher/                    # vendored Fjord launcher releases (gitignored)
├── runtime/                     # authlib-injector.jar
├── tooling/                     # render/fetch/issue scripts (see 08-tooling.md)
├── landing/                     # Astro+TS landing source (build → www/)
├── www/                         # landing build output — caddy apex (gitignored)
├── backups/
└── plan/                        # these files

Service plan files

• 02-caddy.md — internal router (vhost conf.d snippets) behind host nginx
• 03-drasl.md — auth (password login)
• 04-mods.md — distribution-fed mod volume + server filtering (supersedes 04-packwiz.md)
• 05-minecraft.md — itzg NeoForge server
• 06-launcher.md — Fjord launcher fetch + distribution
• 07-mc-backup.md — world backups
• 08-tooling.md — render/fetch/issue scripts
• 09-landing.md — Astro+TS guest onboarding page → www/
• 12-build-order.md — commit-per-task build sequence
• 14-deploy.md — redeploy to the production host
• 15-letsencrypt.md — Let's Encrypt (OVH DNS-01) + host nginx ingress
• 17-mod-shortlist.md — kitchen-sink gap doc + landing mod-list dataset (PLANNED)
• 18-landing-rework.md — join flow / rosters / account / mod list / footer (PLANNED)
• 19-routes.md — HTTP route reference (nmsr / landing / auth / files + internal)
• 20-files.md — Filestash player file share (files., one shared login)
• 23-monitor.md — admin log stream + dashboard (monitor., basic auth)

Boot/dependency order

caddy (aliases) → drasl → minecraft (depends on drasl) → mc-backup. nmsr, mc-status, uptime-kuma, filestash and monitor are always-on and join mcnet (no ordering constraints — none of them are on the auth/boot path). monitor reads Minecraft's log volume and queries its RCON, but starts fine without either: a missing log file and a refused RCON dial are ordinary states it reports rather than errors it dies on.