Phase 3 + 6

inventory-server/deploy/README.md

@@ -0,0 +1,61 @@
+# Server-side deployment artefacts for Phase 3 + 6
+
+This directory contains proposed versions of files that live outside the
+inventory-server tree on production. Each is a recommendation — apply
+deliberately and only after the Node-side ESM + auth changes are deployed and
+smoke-tested.
+
+| Source                                  | Target                                | Phase    |
+| --------------------------------------- | ------------------------------------- | -------- |
+| `Caddyfile.proposed`                    | `/etc/caddy/Caddyfile`                | 6.1, 6.6, 6.7 |
+| `ecosystem.config.cjs.proposed`         | `/var/www/ecosystem.config.cjs`       | 6.4, 6.10 |
+
+## Recommended apply order
+
+1. **Deploy the Node code first** (this repo). PM2 reload picks up the new
+   ESM-mode inventory-server and auth-server. At this point the frontend will
+   start hitting 401s on every API call because the new `authenticate()`
+   middleware is live and the frontend doesn't carry Bearer tokens on most
+   fetches. **This is expected per the discussion in CONSOLIDATION_PLAN.md
+   §6** — the frontend fetch-wrapper work is the next deliverable.
+
+2. **Apply the ecosystem.cjs change** (Phase 6.4) to fix the `JWT_SECRET`
+   shadow-override before the next pm2 restart silently re-introduces it.
+
+3. **Apply the Caddyfile change** (Phase 6.1) only after the frontend is
+   sending Bearer tokens. Until then, `forward_auth` will reject every page
+   refresh at the edge.
+
+## Caddyfile apply pattern
+
+Caddy admin API is on `:2020` (matt has access). On-disk file needs root.
+
+```bash
+# Upload + load atomically into the running Caddy
+curl -X POST http://localhost:2020/load \
+  -H 'Content-Type: text/caddyfile' \
+  --data-binary @/home/matt/Caddyfile.new
+
+# Persist to disk (separate sudo step)
+sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak.$(date +%F)
+sudo cp /home/matt/Caddyfile.new /etc/caddy/Caddyfile
+```
+
+## ecosystem.cjs apply pattern
+
+```bash
+sudo cp /var/www/ecosystem.config.cjs /var/www/ecosystem.config.cjs.bak.$(date +%F)
+sudo cp /home/matt/ecosystem.config.cjs.new /var/www/ecosystem.config.cjs
+pm2 reload ecosystem.config.cjs --update-env
+pm2 env new-auth-server | grep -i jwt    # JWT_SECRET from .env only
+```
+
+## Rollback
+
+Every applied file leaves a `.bak.YYYY-MM-DD` next to it. `sudo cp <bak>
+<original>` then `caddy reload` / `pm2 reload`.
+
+Phase 6 changes are *additive* — if `forward_auth` causes problems, comment
+out the directive in the live Caddyfile and per-server middleware
+(`authenticate()` in inventory-server, in particular) continues protecting
+routes.