feat(tls): Let's Encrypt via OVH DNS-01 + host nginx vhost

tooling/issue-letsencrypt.sh: manual script, issues one cert per name (apex + LE_SUBDOMAINS) with acme.sh + OVH DNS-01 (no inbound ports), installs to certs/<name>/ and reloads nginx. nginx/ulicraft.conf.tmpl: TLS vhosts for apex/pack (static) + auth (proxy to drasl). OVH creds and LE_EMAIL in .env.example; certs/ gitignored. plan/15-letsencrypt.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
refactor(ingress): extract caddy to its own compose file; add nginx path
2026-06-07 23:35:07 +02:00 · 2026-06-07 23:35:07 +02:00 · 2026-06-07 23:22:37 +02:00
12 changed files with 528 additions and 41 deletions
--- a/.claude/skills/deploy/SKILL.md
+++ b/.claude/skills/deploy/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: deploy
+description: Redeploy the Ulicraft Minecraft stack to the production host `cochi` — git pull on main then a hard restart (compose down + build-stack.sh --up online). Use when the user says "deploy", "redeploy", "deploy to cochi", "push to prod", "ship it", or "restart the server" for this project. Causes brief Minecraft downtime.
+---
+
+# Deploy Ulicraft to `cochi`
+
+Redeploy the running stack on the production host. Full reference:
+`plan/14-deploy.md`.
+
+## Fixed parameters
+
+- Host: `cochi` (SSH alias)
+- Path: `/home/ubuntu/mc/ulicraft-server-v1`
+- Branch: `main`
+- Run mode: `online` → compose files `docker-compose.yml` + `docker-compose.static.yml`
+- Auth: Drasl (base stack)
+- Restart: **hard** (down → up) — players are disconnected for a few minutes
+
+## Procedure
+
+This is an outward-facing, downtime-causing action on production. The user
+invoking this skill is the authorization to proceed, but:
+
+1. **Pre-check (read-only).** See what would change before tearing anything down:
+   ```bash
+   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && git fetch && git log --oneline HEAD..@{u}'
+   ```
+   Report the incoming commits. If the list is empty, tell the user the host is
+   already up to date and ask whether to restart anyway (they may want a plain
+   restart). If `git fetch` fails (host unreachable, auth), STOP and report.
+
+2. **Pull + hard restart** (single SSH session, halts on any error):
+   ```bash
+   ssh cochi 'set -e
+     cd /home/ubuntu/mc/ulicraft-server-v1
+     git pull --ff-only
+     docker compose -f docker-compose.yml -f docker-compose.static.yml down --remove-orphans
+     tooling/build-stack.sh --up online'
+   ```
+   - `--ff-only` refuses to merge — if the pull is not a fast-forward, STOP and
+     report (local changes on the host need manual resolution).
+   - `build-stack.sh --up online` renders configs (needs `.env` complete:
+     `BASE_DOMAIN`, `HOST_LAN_IP`, `RCON_PASSWORD`) and runs `compose up -d`.
+
+3. **Verify.**
+   ```bash
+   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && docker compose -f docker-compose.yml -f docker-compose.static.yml ps'
+   ```
+   Confirm `caddy`, `drasl`, `minecraft`, `mc-backup` are Up. Tail the minecraft
+   log briefly and confirm it reaches `Done` (server ready):
+   ```bash
+   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && timeout 120 docker compose -f docker-compose.yml -f docker-compose.static.yml logs -f minecraft' 2>/dev/null | grep -m1 "Done"
+   ```
+
+## Guardrails
+
+- Never `git reset --hard` or discard changes on `cochi` without telling the user
+  first — there may be host-local edits.
+- Volumes (`mc_data`, `drasl_state`) persist across `down`; the world is safe. Do
+  NOT pass `-v`/`--volumes` to `down`.
+- If a step fails, STOP and surface the exact error + the failing command. Do not
+  improvise recovery on production.
+- Blessing Skin variant or `airgap` mode changes the compose file set — if the
+  user asks for those, follow `plan/14-deploy.md` instead of the fixed commands
+  above.
--- a/.env.example
+++ b/.env.example
@@ -18,6 +18,19 @@ RCON_PASSWORD=change-me-to-something-random
 # Only needed if using CurseForge-exclusive mods:
 # CF_API_KEY=your-curseforge-api-key

+# ── Let's Encrypt via OVH DNS-01 (tooling/issue-letsencrypt.sh) ───────
+# Only needed to issue real TLS certs. DNS-01 needs no inbound ports.
+LE_EMAIL=you@example.com
+# space-separated subdomains; apex ${BASE_DOMAIN} is always included
+LE_SUBDOMAINS=auth pack
+# OVH API creds (DNS zone write). Create at https://eu.api.ovh.com/createToken/
+# OVH_CK can be blank on first run — acme.sh prints an auth URL, then paste it.
+OVH_END_POINT=ovh-eu
+OVH_AK=
+OVH_AS=
+OVH_CK=
+# LE_STAGING=1   # use the untrusted staging CA for dry runs
+
 # ── Blessing Skin auth variant (docker-compose.blessingskin.yml) ──────
 # Only needed when running the Blessing Skin override instead of Drasl.
 BS_DB_NAME=blessingskin
--- a/.gitignore
+++ b/.gitignore
@@ -24,3 +24,6 @@ landing/dist/

 # exported Caddy CA (per-deploy artifact)
 caddy/caddy-root-ca.crt
+
+# Let's Encrypt certs + private keys (issued by tooling/issue-letsencrypt.sh)
+certs/
--- a/docker-compose.blessingskin.yml
+++ b/docker-compose.blessingskin.yml
@@ -1,9 +1,11 @@
 # ──────────────────────────────────────────────────────────────────
 # Blessing Skin auth variant — use INSTEAD of Drasl.
 # ──────────────────────────────────────────────────────────────────
-# Layer this over the base file:
+# Layer this over the base file AND the caddy ingress (caddy lives in its own
+# file now; this override only swaps caddy's core conf, so caddy.yml is required):
 #
-#   docker compose -f docker-compose.yml -f docker-compose.blessingskin.yml up -d
+#   docker compose -f docker-compose.yml -f docker-compose.caddy.yml \
+#                  -f docker-compose.blessingskin.yml up -d
 #
 # What it does vs the base stack:
 #   - drasl            → left running but UNUSED + unreachable (Caddy no longer
--- a/docker-compose.caddy.yml
+++ b/docker-compose.caddy.yml
@@ -0,0 +1,46 @@
+# ──────────────────────────────────────────────────────────────────
+# Caddy ingress — LAN / air-gap path. NOT started with the base stack.
+# ──────────────────────────────────────────────────────────────────
+# Caddy was moved out of docker-compose.yml so the base stack can run behind
+# the host's nginx (production) without it. build-stack.sh adds this file for
+# its online/airgap/core modes; static/mirror overrides mount extra vhosts in.
+#
+#   docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d
+#
+# Holds the mcnet aliases (auth./pack.${BASE_DOMAIN}) so containers resolve the
+# stack's own names internally — this is why minecraft can reach the pack here
+# without extra_hosts (the nginx path uses extra_hosts instead).
+services:
+  caddy:
+    image: caddy:alpine
+    container_name: caddy
+    restart: unless-stopped
+    ports:
+      - "80:80"
+    environment:
+      BASE_DOMAIN: ${BASE_DOMAIN}
+    volumes:
+      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
+      - ./caddy/conf.d/00-core.caddy:/etc/caddy/conf.d/00-core.caddy:ro
+      - ./caddy/conf.d/10-static.caddy:/etc/caddy/conf.d/10-static.caddy:ro
+      - ./www:/srv/www:ro
+      - ./mirror/launcher:/srv/launcher:ro
+      - ./caddy/caddy-root-ca.crt:/srv/ca-pub/ca.crt:ro
+      - ./pack:/srv/pack:ro
+      # Custom (locally-hosted) mod jars live OUTSIDE ./pack so packwiz refresh
+      # doesn't index them as direct files. Served at pack.${BASE_DOMAIN}/custom/.
+      - ./custom:/srv/pack/custom:ro
+    networks:
+      mcnet:
+        # The upstream spoof-host aliases live in docker-compose.mirror.yml —
+        # adding them here would hijack maven.neoforged.net etc. for ALL mcnet
+        # containers, breaking the ONLINE NeoForge install during pre-bake.
+        aliases:
+          - "auth.${BASE_DOMAIN}"
+          - "pack.${BASE_DOMAIN}"
+
+  # Restore the ordering the base file used to have (base drops it so it can run
+  # caddy-less behind nginx).
+  minecraft:
+    depends_on:
+      - caddy
--- a/docker-compose.nginx.yml
+++ b/docker-compose.nginx.yml
@@ -0,0 +1,30 @@
+# ──────────────────────────────────────────────────────────────────
+# Production ingress = the HOST's nginx + Let's Encrypt. No caddy.
+# ──────────────────────────────────────────────────────────────────
+#   docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
+#
+# nginx (on the host, already installed) terminates TLS with the LE certs from
+# tooling/issue-letsencrypt.sh and:
+#   - serves apex + pack.${BASE_DOMAIN} as static files (./www, ./pack, ./custom)
+#   - reverse-proxies auth.${BASE_DOMAIN} -> 127.0.0.1:25585 (drasl)
+# See nginx/ulicraft.conf.tmpl.
+#
+# This override:
+#   - publishes drasl on localhost so the host nginx can reach it
+#   - points the minecraft container at the host (extra_hosts) over HTTPS, so it
+#     fetches the pack and validates sessions through the same public names the
+#     LE certs cover (JVM trusts Let's Encrypt out of the box)
+services:
+  drasl:
+    ports:
+      - "127.0.0.1:25585:25585"
+
+  minecraft:
+    # Make the public names resolve to the host running nginx.
+    extra_hosts:
+      - "auth.${BASE_DOMAIN}:host-gateway"
+      - "pack.${BASE_DOMAIN}:host-gateway"
+    environment:
+      # Use HTTPS now that nginx terminates TLS with a publicly-trusted cert.
+      JVM_OPTS: "-javaagent:/extras/authlib-injector.jar=https://auth.${BASE_DOMAIN}/authlib-injector"
+      PACKWIZ_URL: "https://pack.${BASE_DOMAIN}/pack.toml"
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,45 +5,21 @@
 # DNS is provided by YOUR party DNS server — see tooling/dns-records.sh for the
 # records to add (online vs airgap). A turnkey dnsmasq is available as an
 # optional layer: docker-compose.dnsmasq.yml.
-#   - caddy is the only HTTP ingress; holds mcnet aliases so the stack
-#     resolves auth.${BASE_DOMAIN} / packwiz.${BASE_DOMAIN} internally too
+#   - ingress is layered on, NOT in this base file: caddy (docker-compose.caddy.yml,
+#     LAN/air-gap, holds mcnet aliases) OR the host's nginx (docker-compose.nginx.yml
+#     + Let's Encrypt, production)
 #   - drasl handles auth (password login; NO Keycloak/OIDC in this stack)
-#   - packwiz pack is served by caddy at packwiz.${BASE_DOMAIN}
+#   - packwiz pack is served by the ingress at pack.${BASE_DOMAIN}
 #   - minecraft installs mods via PACKWIZ_URL, authlib-injector -> auth.
 # ──────────────────────────────────────────────────────────────────

 services:
-  # Core ingress. Static site + air-gap mirror are layered in via override
-  # files (docker-compose.static.yml / .mirror.yml) — see build-stack.sh --up.
-  caddy:
-    image: caddy:alpine
-    container_name: caddy
-    restart: unless-stopped
-    ports:
-      - "80:80"
-    environment:
-      BASE_DOMAIN: ${BASE_DOMAIN}
-    volumes:
-      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
-      - ./caddy/conf.d/00-core.caddy:/etc/caddy/conf.d/00-core.caddy:ro
-      - ./caddy/conf.d/10-static.caddy:/etc/caddy/conf.d/10-static.caddy:ro
-      - ./www:/srv/www:ro
-      - ./mirror/launcher:/srv/launcher:ro
-      - ./caddy/caddy-root-ca.crt:/srv/ca-pub/ca.crt:ro
-      - ./pack:/srv/pack:ro
-      # Custom (locally-hosted) mod jars live OUTSIDE ./pack so packwiz refresh
-      # doesn't index them as direct files — they're external download targets
-      # referenced by pack/mods/*.pw.toml. Served at pack.${BASE_DOMAIN}/custom/.
-      - ./custom:/srv/pack/custom:ro
-    networks:
-      mcnet:
-        # Only the stack's own subdomains in the base. The upstream spoof-host
-        # aliases live in docker-compose.mirror.yml — adding them here would
-        # hijack maven.neoforged.net / libraries.minecraft.net for ALL mcnet
-        # containers, breaking the ONLINE NeoForge install during pre-bake.
-        aliases:
-          - "auth.${BASE_DOMAIN}"
-          - "pack.${BASE_DOMAIN}"
+  # NOTE: the HTTP(S) ingress is NOT in this base file.
+  #   - LAN / air-gap: caddy (docker-compose.caddy.yml) — added by build-stack.sh
+  #   - production:    the HOST's nginx + Let's Encrypt (docker-compose.nginx.yml
+  #                    publishes drasl to localhost; nginx/ulicraft.conf.tmpl)
+  # Base alone (drasl + minecraft + mc-backup) is not a complete deployment —
+  # always layer one ingress file on top.
  drasl:
    image: unmojang/drasl:latest
    container_name: drasl
@@ -95,7 +71,9 @@ services:
      ENFORCE_SECURE_PROFILE: "FALSE"  # required for authlib-injector on 1.21+
      ALLOW_FLIGHT: "TRUE"             # many tech mods need this

-      # ── Mod source: packwiz pack served by caddy ────────────────
+      # ── Mod source: packwiz pack served by the ingress ──────────
+      # http + caddy alias by default; the nginx override switches this to
+      # https + host-gateway (extra_hosts) for the production path.
      PACKWIZ_URL: "http://pack.${BASE_DOMAIN}/pack.toml"

      # ── RCON for remote admin ───────────────────────────────────
@@ -108,8 +86,7 @@ services:
      - mc_data:/data
      - ./runtime:/extras:ro       # authlib-injector.jar lives here
    depends_on:
-      - drasl
-      - caddy                      # packwiz pack is served by caddy
+      - drasl                      # ingress (caddy/nginx) is layered separately
    networks:
      - mcnet

--- a/nginx/ulicraft.conf.tmpl
+++ b/nginx/ulicraft.conf.tmpl
@@ -0,0 +1,83 @@
+# ──────────────────────────────────────────────────────────────────
+# Ulicraft host nginx — TLS ingress with Let's Encrypt certs.
+# ──────────────────────────────────────────────────────────────────
+# Template. Render with BOTH vars then install:
+#
+#   APP_DIR=/home/ubuntu/mc/ulicraft-server-v1 BASE_DOMAIN=ulicraft.net \
+#     envsubst '$APP_DIR $BASE_DOMAIN' \
+#     < nginx/ulicraft.conf.tmpl | sudo tee /etc/nginx/sites-available/ulicraft.conf
+#   sudo ln -sf /etc/nginx/sites-available/ulicraft.conf /etc/nginx/sites-enabled/
+#   sudo nginx -t && sudo systemctl reload nginx
+#
+# Prereqs:
+#   - certs issued: tooling/issue-letsencrypt.sh  -> $APP_DIR/certs/<name>/{cert,key}.pem
+#   - the docker stack up with the nginx override (publishes drasl on 127.0.0.1:25585):
+#       docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
+#   - nginx's user (www-data) can READ $APP_DIR/{www,pack,custom,certs}
+# ──────────────────────────────────────────────────────────────────
+
+# HTTP -> HTTPS for every name.
+server {
+    listen 80;
+    listen [::]:80;
+    server_name ${BASE_DOMAIN} auth.${BASE_DOMAIN} pack.${BASE_DOMAIN};
+    return 301 https://$host$request_uri;
+}
+
+# Apex — static landing page.
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    http2 on;
+    server_name ${BASE_DOMAIN};
+
+    ssl_certificate     ${APP_DIR}/certs/${BASE_DOMAIN}/cert.pem;
+    ssl_certificate_key ${APP_DIR}/certs/${BASE_DOMAIN}/key.pem;
+
+    root ${APP_DIR}/www;
+    index index.html;
+    location / { try_files $uri $uri/ =404; }
+}
+
+# Pack — packwiz metadata (./pack) + custom jars (./custom at /custom/).
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    http2 on;
+    server_name pack.${BASE_DOMAIN};
+
+    ssl_certificate     ${APP_DIR}/certs/pack.${BASE_DOMAIN}/cert.pem;
+    ssl_certificate_key ${APP_DIR}/certs/pack.${BASE_DOMAIN}/key.pem;
+
+    # Locally-hosted custom mod jars live outside ./pack; expose them at /custom/.
+    location /custom/ {
+        alias ${APP_DIR}/custom/;
+        autoindex on;
+    }
+
+    location / {
+        root ${APP_DIR}/pack;
+        autoindex on;
+    }
+}
+
+# Auth — reverse proxy to drasl (published on localhost by the nginx override).
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    http2 on;
+    server_name auth.${BASE_DOMAIN};
+
+    ssl_certificate     ${APP_DIR}/certs/auth.${BASE_DOMAIN}/cert.pem;
+    ssl_certificate_key ${APP_DIR}/certs/auth.${BASE_DOMAIN}/key.pem;
+
+    client_max_body_size 4m;   # skin uploads
+
+    location / {
+        proxy_pass http://127.0.0.1:25585;
+        proxy_set_header Host              $host;
+        proxy_set_header X-Real-IP         $remote_addr;
+        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
--- a/plan/14-deploy.md
+++ b/plan/14-deploy.md
@@ -0,0 +1,86 @@
+# Deployment — redeploy to `cochi`
+
+Production host for the Ulicraft stack.
+
+| | |
+|---|---|
+| Host | `cochi` (SSH alias) |
+| Path | `/home/ubuntu/mc/ulicraft-server-v1` |
+| Branch | `main` |
+| Run mode | `online` (compose files: `docker-compose.yml` + `docker-compose.static.yml`) |
+| Auth | Drasl (base stack — no Blessing Skin override) |
+| Restart | **hard** (`compose down` → `build-stack.sh --up`) — brief full downtime |
+
+## Routine redeploy
+
+```bash
+ssh cochi
+cd /home/ubuntu/mc/ulicraft-server-v1
+git pull --ff-only
+# hard restart: tear the stack down, then bring it back up (renders configs first)
+docker compose -f docker-compose.yml -f docker-compose.static.yml down --remove-orphans
+tooling/build-stack.sh --up online
+```
+
+Or as a one-shot from your workstation:
+
+```bash
+ssh cochi 'set -e
+  cd /home/ubuntu/mc/ulicraft-server-v1
+  git pull --ff-only
+  docker compose -f docker-compose.yml -f docker-compose.static.yml down --remove-orphans
+  tooling/build-stack.sh --up online'
+```
+
+`build-stack.sh --up online` runs preflight (checks `.env`), `render-config.sh`
+(which renders configs + `render-pack.sh` for the packwiz pack), then
+`docker compose ... up -d` with the online file set.
+
+## What survives a hard restart
+
+Named volumes persist — world and auth data are safe:
+- `mc_data` — world + installed NeoForge/mods
+- `drasl_state` — Drasl accounts/skins
+- `backups/` — mc-backup snapshots
+
+`down` removes **containers**, not volumes. Players are disconnected during the
+restart (a few minutes); they reconnect once `minecraft` is healthy again.
+
+## Prerequisites (one-time, on `cochi`)
+
+- SSH access as the `cochi` alias.
+- `.env` present and complete: `BASE_DOMAIN`, `HOST_LAN_IP`, `RCON_PASSWORD`
+  (`render-config.sh` halts on any unset var, even in online mode).
+- Docker + compose plugin, `packwiz`, `envsubst`, `git`.
+- **First deploy only** — heavy online prep (fetch launcher, pre-bake the server
+  volume, etc.):
+  ```bash
+  tooling/build-stack.sh --prep
+  ```
+  Not needed for routine redeploys; `--up` alone re-syncs the pack and configs.
+
+## Verify
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.static.yml ps
+docker compose -f docker-compose.yml -f docker-compose.static.yml logs -f minecraft   # watch for "Done"
+curl -fsS "http://auth.$(grep '^BASE_DOMAIN=' .env | cut -d= -f2)/" >/dev/null && echo "auth ok"
+```
+
+## Rollback
+
+```bash
+git log --oneline -5            # find the last-good commit
+git checkout <sha>              # or: git reset --hard <sha>
+docker compose -f docker-compose.yml -f docker-compose.static.yml down --remove-orphans
+tooling/build-stack.sh --up online
+```
+
+## Notes
+
+- **Online mode needs internet** on `cochi` at restart (no air-gap mirror): the
+  server installs NeoForge + mods over the network. For an internet-less deploy,
+  switch to `airgap` (needs `--prep` first) — see `plan/13-dns-and-run-modes.md`.
+- Switching to the **Blessing Skin** auth variant changes the file set to
+  `-f docker-compose.yml -f docker-compose.blessingskin.yml` (see
+  `plan/03b-blessing-skin.md`); update the `down`/`up` commands accordingly.
--- a/plan/15-letsencrypt.md
+++ b/plan/15-letsencrypt.md
@@ -0,0 +1,76 @@
+# TLS — Let's Encrypt (OVH DNS-01) + host nginx ingress
+
+Production serves real, publicly-trusted certs via the **host's nginx**. Caddy is
+no longer the production ingress — it moved to its own compose file for the
+LAN/air-gap path.
+
+## Two ingress paths
+
+| Path | Ingress | Compose | TLS |
+|------|---------|---------|-----|
+| Production | host **nginx** | `docker-compose.yml` + `docker-compose.nginx.yml` | Let's Encrypt (this doc) |
+| LAN / air-gap | **caddy** container | `docker-compose.yml` + `docker-compose.caddy.yml` (+ static/mirror) | Caddy internal CA |
+
+`build-stack.sh` drives the caddy path (adds `docker-compose.caddy.yml`
+automatically). The nginx path is a manual deploy (below). This supersedes the
+ingress part of `plan/14-deploy.md` for production.
+
+## Certs: one per name, via OVH DNS-01
+
+`tooling/issue-letsencrypt.sh` issues a **separate** cert for the apex and each
+subdomain (`${BASE_DOMAIN}`, `auth.…`, `pack.…`) using acme.sh + the OVH DNS-01
+challenge — no inbound ports needed, so it works even on a LAN-only host.
+
+### One-time setup
+
+1. Install acme.sh:
+   ```bash
+   curl https://get.acme.sh | sh -s email=you@example.com
+   ```
+2. OVH API credentials → `.env` (see `.env.example` `OVH_*`, `LE_EMAIL`,
+   `LE_SUBDOMAINS`). Create a token at <https://eu.api.ovh.com/createToken/> with
+   `GET/POST/PUT/DELETE` on `/domain/zone/*`, or leave `OVH_CK` blank and run the
+   script once — acme.sh prints an authorization URL; visit it, then paste the
+   consumer key into `OVH_CK` and re-run.
+
+### Issue
+
+```bash
+tooling/issue-letsencrypt.sh             # real certs
+LE_STAGING=1 tooling/issue-letsencrypt.sh  # dry run against the LE staging CA
+```
+
+Certs install to `certs/<name>/{cert.pem,key.pem}` (gitignored). acme.sh adds a
+cron for renewal; `--reloadcmd` reloads nginx automatically on renew. Override
+the reload with `RELOAD_CMD=...` if nginx isn't systemd-managed.
+
+## nginx
+
+1. Stack up with the nginx override (publishes drasl on `127.0.0.1:25585`):
+   ```bash
+   docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d
+   ```
+2. Render + install the vhost (`nginx/ulicraft.conf.tmpl`):
+   ```bash
+   APP_DIR=/home/ubuntu/mc/ulicraft-server-v1 BASE_DOMAIN=ulicraft.net \
+     envsubst '$APP_DIR $BASE_DOMAIN' \
+     < nginx/ulicraft.conf.tmpl | sudo tee /etc/nginx/sites-available/ulicraft.conf
+   sudo ln -sf /etc/nginx/sites-available/ulicraft.conf /etc/nginx/sites-enabled/
+   sudo nginx -t && sudo systemctl reload nginx
+   ```
+   nginx then: apex + `pack.*` as static files (`www`, `pack`, `custom`),
+   `auth.*` → drasl. Ensure `www-data` can read `$APP_DIR/{www,pack,custom,certs}`.
+
+## DNS
+
+Point the public/party DNS for `${BASE_DOMAIN}`, `auth.${BASE_DOMAIN}`,
+`pack.${BASE_DOMAIN}` at the host. The Minecraft container reaches them via
+`extra_hosts: host-gateway` (set in `docker-compose.nginx.yml`) and uses HTTPS —
+the JVM trusts Let's Encrypt with no CA import (the big win over the internal CA).
+
+## Why DNS-01 (not HTTP-01)
+
+`HOST_LAN_IP` shows a LAN host; HTTP-01/TLS-ALPN-01 need public inbound on 80/443.
+DNS-01 only needs the OVH API, so it issues regardless of public reachability —
+and `ulicraft.net` is a real OVH-managed domain, which LE requires (it never
+issues for `.lan`/`.local`).
--- a/tooling/build-stack.sh
+++ b/tooling/build-stack.sh
@@ -91,7 +91,8 @@ prep() {
  log "pre-bake server volume (TYPE=NEOFORGE install, one-shot, online)"
  # Bring minecraft up once so itzg installs NeoForge + mods into the volume,
  # then stop it. The party then runs offline against the baked volume.
-  "${COMPOSE[@]}" up -d minecraft
+  # caddy.yml so the pack (pack.${BASE_DOMAIN}) resolves + is served during bake.
+  "${COMPOSE[@]}" -f docker-compose.yml -f docker-compose.caddy.yml up -d minecraft
  warn "watch logs until 'Done' then re-run with --up; or automate a readiness probe"
 }

@@ -102,7 +103,10 @@ prep() {
 #   core    base only (no landing, no mirror) — debugging
 up() {
  local mode="${1:-airgap}"
-  local -a files=(-f docker-compose.yml)
+  # build-stack is the caddy (LAN/air-gap) deployer; caddy lives in its own file
+  # now (the base stack can also run behind the host's nginx — see
+  # docker-compose.nginx.yml). Always include caddy here.
+  local -a files=(-f docker-compose.yml -f docker-compose.caddy.yml)
  case "$mode" in
    core)   ;;
    online) files+=(-f docker-compose.static.yml) ;;
--- a/tooling/issue-letsencrypt.sh
+++ b/tooling/issue-letsencrypt.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# issue-letsencrypt.sh — issue per-name Let's Encrypt certificates via the OVH
+# DNS-01 challenge (acme.sh) and install them where Caddy serves them.
+#
+# Run MANUALLY on the host. One separate certificate per name:
+#   ${BASE_DOMAIN}  +  <sub>.${BASE_DOMAIN} for each sub in LE_SUBDOMAINS.
+# Certs land in certs/<name>/{cert.pem,key.pem} (gitignored) and the host nginx
+# is reloaded so it picks them up (see nginx/ulicraft.conf.tmpl).
+#
+# DNS-01 needs no inbound ports — works for a LAN-only host. It only needs OVH
+# API credentials with DNS-record write access for the zone.
+#
+# .env vars required:
+#   BASE_DOMAIN       e.g. ulicraft.net
+#   LE_EMAIL          account email for Let's Encrypt
+#   OVH_AK OVH_AS     OVH application key + secret
+#   OVH_CK            OVH consumer key (obtained on first run — see below)
+#   OVH_END_POINT     OVH API endpoint (e.g. ovh-eu)
+# optional:
+#   LE_SUBDOMAINS     space-separated (default: "auth pack")
+#   LE_STAGING=1      use the LE staging CA (untrusted, for dry runs)
+#
+# First-time OVH consumer key: set OVH_AK/OVH_AS/OVH_END_POINT, leave OVH_CK
+# empty, run this once — acme.sh prints an authorization URL. Visit it, grant
+# access, then copy the consumer key it shows into OVH_CK in .env and re-run.
+# (Or create a token directly: https://eu.api.ovh.com/createToken/ with
+#  GET/POST/PUT/DELETE on /domain/zone/*.)
+set -euo pipefail
+
+cd "$(dirname "$0")/.."   # repo root
+
+log()  { printf '\n\033[1;32m==>\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m!!\033[0m %s\n' "$*" >&2; }
+die()  { printf '\033[1;31mxx\033[0m %s\n' "$*" >&2; exit 1; }
+
+# ---- config / preflight ----------------------------------------------------
+[ -f .env ] || die ".env not found (copy .env.example and fill it)"
+# shellcheck disable=SC1091
+set -a; . ./.env; set +a
+: "${BASE_DOMAIN:?BASE_DOMAIN unset in .env}"
+: "${LE_EMAIL:?LE_EMAIL unset in .env}"
+: "${OVH_AK:?OVH_AK unset in .env}"
+: "${OVH_AS:?OVH_AS unset in .env}"
+: "${OVH_END_POINT:?OVH_END_POINT unset in .env (e.g. ovh-eu)}"
+# OVH_CK may be empty on the very first run (acme.sh will print the auth URL).
+export OVH_AK OVH_AS OVH_END_POINT
+export OVH_CK="${OVH_CK:-}"
+
+ACME="${ACME_SH:-$HOME/.acme.sh/acme.sh}"
+[ -x "$ACME" ] || ACME="$(command -v acme.sh || true)"
+[ -n "$ACME" ] && [ -x "$ACME" ] || die "acme.sh not found. Install:
+  curl https://get.acme.sh | sh -s email=${LE_EMAIL}
+then re-run (or set ACME_SH=/path/to/acme.sh)."
+
+CERT_DIR="${CERT_DIR:-certs}"
+read -r -a SUBDOMAINS <<< "${LE_SUBDOMAINS:-auth pack}"
+
+if [ "${LE_STAGING:-0}" = "1" ]; then
+  SERVER="letsencrypt_test"; warn "STAGING mode — certs will NOT be trusted by browsers"
+else
+  SERVER="letsencrypt"
+fi
+
+# Reload the host nginx after each install so new certs take effect. Override
+# RELOAD_CMD if nginx runs elsewhere (e.g. a container or a non-systemd host).
+RELOAD="${RELOAD_CMD:-sudo systemctl reload nginx} || true"
+
+# Full name list: apex + each subdomain.
+domains=("$BASE_DOMAIN")
+for s in "${SUBDOMAINS[@]}"; do domains+=("${s}.${BASE_DOMAIN}"); done
+
+log "CA=$SERVER  names: ${domains[*]}"
+
+# Register the ACME account once (idempotent).
+"$ACME" --register-account -m "$LE_EMAIL" --server "$SERVER" >/dev/null 2>&1 || true
+
+# ---- issue + install one cert per name --------------------------------------
+issued=0
+for d in "${domains[@]}"; do
+  log "issuing $d (OVH DNS-01)"
+  rc=0
+  "$ACME" --issue --dns dns_ovh --server "$SERVER" --keylength ec-256 -d "$d" || rc=$?
+  # acme.sh: 0 = issued/renewed, 2 = skipped (cert still valid, not due). Both ok.
+  case "$rc" in
+    0|2) ;;
+    *) die "acme.sh failed for $d (rc=$rc). If this is the first OVH run, follow
+        the consumer-key authorization URL printed above, set OVH_CK in .env, re-run." ;;
+  esac
+
+  mkdir -p "$CERT_DIR/$d"
+  "$ACME" --install-cert -d "$d" --ecc \
+    --key-file       "$CERT_DIR/$d/key.pem" \
+    --fullchain-file "$CERT_DIR/$d/cert.pem" \
+    --reloadcmd      "$RELOAD"
+  echo "  installed -> $CERT_DIR/$d/{cert.pem,key.pem}"
+  issued=$((issued+1))
+done
+
+log "done — $issued certificate(s) under $CERT_DIR/"
+echo "  serve them: point nginx at certs/<name>/ — see nginx/ulicraft.conf.tmpl"
+echo "  renewals: acme.sh installs a cron; --reloadcmd reloads nginx automatically."