Oier Bravo Urtasun
3185fea4c1
Add tooling/render-nginx.sh: pulls BASE_DOMAIN/CADDY_HTTP_PORT from .env,
defaults APP_DIR to the repo checkout, renders a vhost template (default the
caddy-front one) to stdout, or --install writes + symlinks + nginx -t + reloads.
Document it in the README, replacing the manual envsubst one-liner.
Also add the www.${BASE_DOMAIN} canonical 301->apex block and put www in the
LE_SUBDOMAINS default so its cert is issued.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
156 lines
6.6 KiB
Markdown
156 lines
6.6 KiB
Markdown
# Ulicraft Server
|
||
|
||
Self-hosted modded Minecraft (NeoForge 1.21.1) for a LAN party. Runs **online**
|
||
(internet present) or **fully air-gapped** (offline). Self-hosted auth/skins
|
||
(Drasl), a packwiz modpack, a guest landing page, and a transparent mirror of
|
||
Mojang/launcher/NeoForge assets so guest laptops need no internet.
|
||
|
||
## Stack
|
||
|
||
| Service | Image | Role |
|
||
|---|---|---|
|
||
| `minecraft` | itzg/minecraft-server | NeoForge 1.21.1 server, `:25565` |
|
||
| `drasl` | unmojang/drasl | Yggdrasil auth + skins (password login) |
|
||
| `caddy` | caddy:alpine | ingress: landing, auth/packwiz proxy, asset mirror (`tls internal`) |
|
||
| `mc-backup` | itzg/mc-backup | world backups every 6h via RCON |
|
||
|
||
Optional layers: `avahi` (mDNS `.local`), `dnsmasq` (turnkey DNS) — only if you
|
||
don't run your own DNS.
|
||
|
||
Config lives in `.env`: `BASE_DOMAIN` (default `ulicraft.lan`), `HOST_LAN_IP`,
|
||
`RCON_PASSWORD`, `ENABLE_MDNS`. Services are subdomains: `auth.`, `packwiz.`,
|
||
`mc.`, plus the apex landing page.
|
||
|
||
## DNS (pick one)
|
||
|
||
Names must resolve to `HOST_LAN_IP`. Use **your own party DNS server** (recommended):
|
||
|
||
```sh
|
||
tooling/dns-records.sh online # service names only (internet present)
|
||
tooling/dns-records.sh airgap # + Mojang/launcher/NeoForge spoofs (offline)
|
||
```
|
||
Paste the printed records into your DNS. **Use `.lan`, not `.local`** — `.local`
|
||
is intercepted by mDNS and won't resolve via unicast DNS.
|
||
|
||
Alternatives: `ENABLE_MDNS=true` + `BASE_DOMAIN=*.local` (zero-config mDNS,
|
||
macOS/Linux native, Windows needs Bonjour) — but mDNS can't serve the air-gap
|
||
upstream spoofs. Or layer in `docker-compose.dnsmasq.yml` for a turnkey DNS.
|
||
|
||
### Simulate the DNS via /etc/hosts (single machine, testing)
|
||
|
||
No DNS server? Append the records straight to `/etc/hosts` (marker-wrapped):
|
||
|
||
```sh
|
||
tooling/dns-records.sh online hosts | sudo tee -a /etc/hosts # services only
|
||
tooling/dns-records.sh airgap hosts | sudo tee -a /etc/hosts # + Mojang spoofs
|
||
```
|
||
|
||
Remove them later:
|
||
|
||
```sh
|
||
sudo sed -i '/# >>> ulicraft/,/# <<< ulicraft/d' /etc/hosts
|
||
```
|
||
|
||
Notes:
|
||
- `/etc/hosts` has **no wildcard** — only the listed names resolve.
|
||
- `airgap` adds the Mojang/launcher/NeoForge hostnames pointing at the LAN; this
|
||
**breaks normal internet access to those domains** while present. Use it only
|
||
while offline; for an online box use `online`.
|
||
- `mc.<domain>` works (client defaults to :25565); SRV isn't used via `/etc/hosts`.
|
||
|
||
## Prerequisites
|
||
|
||
Docker + Docker Compose; for prep also `pnpm`, `packwiz`, `jq`, `curl`,
|
||
`envsubst`, `sha1sum`.
|
||
|
||
## Launch
|
||
|
||
```sh
|
||
cp .env.example .env # set BASE_DOMAIN, HOST_LAN_IP, RCON_PASSWORD
|
||
|
||
tooling/build-stack.sh --prep # ONLINE, once: render, build landing,
|
||
# mirror mods+assets, fetch launcher +
|
||
# authlib, pre-bake the server volume
|
||
|
||
tooling/build-stack.sh --up online # internet present, no mirror
|
||
tooling/build-stack.sh --up airgap # offline; full asset mirror on :443 (default)
|
||
tooling/build-stack.sh --up core # base only (debugging)
|
||
```
|
||
|
||
`--up` prints the DNS records to add for that mode. Down:
|
||
`docker compose -f docker-compose.yml -f docker-compose.static.yml -f docker-compose.mirror.yml down`
|
||
|
||
## Public TLS (host nginx in front of caddy)
|
||
|
||
The LAN path above runs caddy on `:80`. To expose the stack publicly with real
|
||
certs, the machine's own nginx terminates TLS and reverse-proxies every vhost to
|
||
caddy by Host header. Caddy stays the single router (apex landing, `auth.`
|
||
→ drasl, `pack.` packwiz, `distribution.` static).
|
||
|
||
1. **Issue certs** (OVH DNS-01, no inbound ports needed):
|
||
```sh
|
||
# .env: BASE_DOMAIN, LE_EMAIL, OVH_* creds, LE_SUBDOMAINS="auth pack distribution"
|
||
tooling/issue-letsencrypt.sh # → certs/<name>/{cert,key}.pem
|
||
```
|
||
|
||
2. **Bind caddy to a localhost-only port** so only nginx reaches it (`.env`):
|
||
```sh
|
||
CADDY_HTTP_PORT=8880
|
||
CADDY_HTTP_BIND=127.0.0.1
|
||
```
|
||
|
||
3. **Bring up the caddy ingress** (+ static, + distribution if used):
|
||
```sh
|
||
docker compose -f docker-compose.yml -f docker-compose.caddy.yml \
|
||
-f docker-compose.static.yml -f docker-compose.distribution.yml up -d
|
||
```
|
||
|
||
4. **Render + install the nginx vhost** with `tooling/render-nginx.sh`. It pulls
|
||
`BASE_DOMAIN` + `CADDY_HTTP_PORT` from `.env`, defaults `APP_DIR` to the repo
|
||
checkout (where `certs/` live), and renders `nginx/ulicraft-caddy.conf.tmpl`:
|
||
```sh
|
||
tooling/render-nginx.sh # preview to stdout (dry run)
|
||
tooling/render-nginx.sh --install # write, symlink, nginx -t, reload
|
||
```
|
||
Overrides via env: `APP_DIR=/path` (if the repo isn't at the cert location),
|
||
`SITE_NAME=foo.conf`, `TEMPLATE=nginx/ulicraft.conf.tmpl` (the static variant —
|
||
nginx serves the files itself + proxies only drasl; pick one, not both).
|
||
|
||
Re-run step 4 whenever you add a subdomain so its server block is rendered.
|
||
|
||
`distribution.${BASE_DOMAIN}` serves a static site whose web root lives in
|
||
another repo: set `DISTRIBUTION_WEB_ROOT` (absolute host path) in `.env`; it's
|
||
bind-mounted read-only via `docker-compose.distribution.yml`.
|
||
|
||
## Join (guests)
|
||
|
||
1. Open `http://ulicraft.lan`, download FjordLauncherUnlocked for your OS.
|
||
2. Add an **authlib-injector** account, URL `http://auth.ulicraft.lan/authlib-injector`
|
||
(register/login at `http://auth.ulicraft.lan`).
|
||
3. **Air-gap only:** trust the local CA — download `http://ulicraft.lan/ca.crt`
|
||
and add it to your OS trust store (so the HTTPS asset mirror is trusted).
|
||
4. Import the pack: `http://packwiz.ulicraft.lan/pack.toml`.
|
||
5. Connect to **`mc.ulicraft.lan`** (no port needed).
|
||
|
||
## Layout
|
||
|
||
```
|
||
docker-compose.yml # core: drasl, minecraft, mc-backup, caddy
|
||
.static.yml .mirror.yml # online/airgap layers
|
||
.avahi.yml .dnsmasq.yml # optional DNS layers
|
||
caddy/Caddyfile + conf.d/*.caddy # ingress vhost snippets (core/static/mirror)
|
||
drasl/config/config.toml.tmpl # auth config (rendered)
|
||
dnsmasq/dnsmasq.conf.tmpl # optional DNS config (rendered)
|
||
docker/avahi/ # mDNS responder image
|
||
pack/ # packwiz modpack source
|
||
landing/ # Astro site → www/
|
||
tooling/ # build-stack, render-config, render-nginx,
|
||
# dns-records, issue-letsencrypt,
|
||
# mirror-mods, mirror-airgap, fetch-launcher
|
||
nginx/*.conf.tmpl # host-nginx TLS vhost templates
|
||
mirror/ # vendored jars + launcher + asset mirror (gitignored)
|
||
plan/ # full design docs (00–12)
|
||
```
|
||
|
||
See `plan/00-overview.md` for the full design.
|