ulicraft-server-v1/.claude/skills/deploy/SKILL.md

---
name: deploy
description: Redeploy the Ulicraft Minecraft stack to the production host `cochi` — git pull on main then a hard restart (compose down + up). 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`
- Stack: single unified `docker-compose.yml` (drasl, minecraft, mc-backup,
  caddy, nmsr, mc-status, uptime-kuma, filestash)
- Auth: Drasl
- 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.

   **If the incoming commits ADD A SERVICE, check `.env` on the host first.**
   A new service with `${FOO:?...}` guards (filestash uses them) fails the
   **whole compose file**, not just that service — so a missing var means
   `up` refuses to start *anything*, and a `--hard` deploy has already run
   `down`. The stack stays down. Check before tearing it down:
   ```bash
   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && grep -c "^FILES_" .env'
   ```
   Same for a new **subdomain**: it needs a cert (`LE_SUBDOMAINS` +
   `issue-letsencrypt.sh`) and an nginx vhost — see step 2b, which the deploy
   does NOT do for you.

2. **Pull, ensure authlib, then `update-all.sh --hard`** (single SSH session,
   halts on any error):
   ```bash
   ssh cochi 'set -e
     cd /home/ubuntu/mc/ulicraft-server-v1
     git pull --ff-only
     tooling/fetch-authlib.sh
     ./update-all.sh --hard'
   ```
   - `--ff-only` refuses to merge — if the pull is not a fast-forward, STOP and
     report (local changes on the host need manual resolution).
   - `fetch-authlib.sh` ensures `runtime/authlib-injector.jar` exists (gitignored;
     skips if already valid; NOT part of update-all since it rarely changes).
     Missing jar = minecraft crashloops with "Error opening zip file or JAR
     manifest missing". Run it before `update-all` so the jar is present when
     compose brings minecraft up.
   - **`update-all.sh` is the single source of truth** for the post-pull build +
     restart steps (render drasl/nmsr configs from `.env`, sync server mods, regen
     the landing mod list, rebuild `www/`, then apply via docker compose). It is
     also runnable on its own for a lighter rolling update (no `--hard` =
     change-detected restart, no world downtime). `--hard` here does
     `down --remove-orphans && up -d --build` for the deliberate full restart.
     `render-config.sh` halts on an invalid `REGISTRATION_MODE` (must be `invite`
     or `open`); a missing distribution jar halts `sync-server-mods.sh`. The
     landing rebuild is unconditional (the gitignored `www/` is never updated by
     `git pull`), so no separate landing step is needed.

2b. **Only if the deploy changed `nginx/ulicraft-caddy.conf.tmpl`** (a new
   subdomain, a new body-size/rate-limit rule, a changed `CADDY_HTTP_PORT`).
   `update-all.sh` does **not** touch the host nginx, so a new vhost simply
   won't exist and the subdomain 404s / hits the wrong server block:
   ```bash
   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && tooling/render-nginx.sh --install'
   ```
   It runs `nginx -t` before reloading, so a bad render fails safe. The cert
   must already exist (`certs/<name>/cert.pem`) or nginx won't load the block —
   issue it first with `tooling/issue-letsencrypt.sh` (reads `LE_SUBDOMAINS`).

3. **Verify.**
   ```bash
   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && docker compose ps'
   ```
   Confirm `caddy`, `drasl`, `minecraft`, `mc-backup`, `nmsr`, `mc-status`,
   `uptime-kuma`, `filestash` are Up. Tail the minecraft log briefly and confirm
   it reaches the ready marker (match `Done (Ns)! For help` — a bare `Done`
   also matches unrelated mod-loading lines):
   ```bash
   ssh cochi 'cd /home/ubuntu/mc/ulicraft-server-v1 && timeout 180 docker compose logs -f minecraft' 2>/dev/null | grep -m1 'Done ([0-9.]*s)! For help'
   ```
   If a public vhost changed, verify it end-to-end from your workstation rather
   than trusting `compose ps` (a container can be Up while nginx never routes to
   it): `curl -s -o /dev/null -w '%{http_code}' https://<vhost>/`.

## Guardrails

- Never `git reset --hard` or discard changes on `cochi` without telling the user
  first — there may be host-local edits.
- **Caddy conf changes need a recreate, not reload/restart.** If the deploy
  touched any `caddy/conf.d/*.caddy` or the Caddyfile and you did a *rolling*
  `update-all.sh` (not `--hard`), the change WON'T apply: those are single-file
  bind mounts pinned to the host inode, and `git pull` gives the file a new inode.
  `restart`/`caddy reload` reuse the stale inode. Run
  `docker compose up -d --force-recreate caddy`, then verify with
  `docker compose exec caddy cat /etc/caddy/conf.d/<file>`. The `--hard` path
  (full `down`/`up`) already recreates, so it's unaffected.
- **Same trap for `filestash/config.json`** — also a single-file bind mount, and
  it is *re-rendered on every run* by `render-config.sh`, so a rolling
  `update-all.sh` leaves filestash reading the stale inode after any `FILES_*`
  change (rotating the shared password, flipping `FILES_AUTH`). Apply with
  `docker compose up -d --force-recreate filestash`. `--hard` is unaffected.
- **Never let `filestash/config.json` be missing when compose runs.** It is
  gitignored and rendered; if it doesn't exist, Docker creates a *directory* at
  that path and filestash breaks in a confusing way. `update-all.sh` renders
  before `up`, so the normal path is safe — just don't hand-run `docker compose
  up` on the host without rendering first. If it happened: `rm -rf
  filestash/config.json && tooling/render-config.sh && docker compose up -d
  --force-recreate filestash`.
- Volumes (`mc_data`, `drasl_state`, `kuma_data`) persist across `down`; the
  world and monitors are 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.