📋 Operational Runbooks
Executive Summary What this is: The central index for operational procedures, deployment scripts, and troubleshooting guides for the Funday platform. When to use: When deploying services, verifying health, or troubleshooting live environments. INTENDED vs LIVE: Vault/ESO and some Nakama “production complete” language may describe intended control plane — check banners on Secrets and Nakama multiplayer.
Safe behaviors: Use standard scripts over manual intervention. Always verify health post-deployment. Never leak or log operational secrets in chat or documentation.
Find
Quick reference for common operational tasks and commands.
| Runbook | When to use | Command / path |
|---|---|---|
| Shipping truth & hidden work | Before choosing what to work on next — deploy model, gitignored prod artifacts, stash/worktree ledger | Shipping Truth cheat sheet |
| Frontend deploy | After frontend or game-host changes | bash /home/usr/funday/scripts/build-atomic.sh |
| Frontend health | After deploy/restart | curl -sf http://127.0.0.1:3000/health |
| Nakama module build | After nakama-modules/*.ts changes | cd /home/usr/funday/nakama-modules && npm run build |
| Nakama restart | After verified Nakama bundle change | sudo k3s kubectl rollout restart deployment/nakama -n funday-platform |
| Wiki rebuild | After wiki content/config changes | cd /home/usr/funday/dev/docs && npx quartz build && sudo systemctl restart quartz-wiki |
| Wiki watcher | Confirm auto-builder service | sudo systemctl status quartz-wiki |
| nginx reload | After nginx config changes | sudo nginx -t && sudo systemctl reload nginx |
| Ompcord daemon | After Amy/Ompcord config/code changes | sudo systemctl reload amyd or node /home/usr/pi-discord-amy/redeploy.mjs |
Implement
Step-by-step procedures for deploying and operating services.
Frontend deploy
See the canonical Frontend deploy runbook for preflight checks, the supported entry point, artifact gates, rollback, and prohibited paths.
Nakama deploy
cd /home/usr/funday/nakama-modules
npm run build
sudo k3s kubectl rollout restart deployment/nakama -n funday-platform
sudo k3s kubectl rollout status deployment/nakama -n funday-platform
curl -sf https://funday.gg/v2/healthcheckEdit TypeScript sources, then rebuild. Do not hand-edit generated nakama-modules/index.js.
Wiki publication
For production publication (atomic release with staging and pointer swap):
cd /home/usr/funday/dev/docs
npm run build:docsContent-only updates do not require a frontend build or service restart.
For local, non-publishing validation of edits before publication:
cd /home/usr/funday/dev/docs
npx quartz build --output /tmp/quartz-validate-$$
rm -rf /tmp/quartz-validate-*Served at funday.gg/dev/docs/wiki/ (iframe) behind nginx; shell at funday.gg/dev/docs.
Ompcord/Amy checks
Amy runs as amyd.service (enabled on boot, Restart=always). Credentials: ~/.omp/.env (OMPCORD_DISCORD_*) → bootstrap → ~/.config/amy/amyd.env. Separate from Hoe/Hermes — see Ompcord deployment.
sudo systemctl status amyd.service
tail -5 /home/usr/pi-discord-amy/amyd.log # ONLINE as Amy#0305
node /home/usr/pi-discord-amy/scripts/bootstrap-amy-env.mjs # after ~/.omp/.env changes
cd /home/usr/pi-discord-amy && bun testDetailed Procedures
- Dev Access Gating — Setting up access control for
/devand/dev/docs - Frontend Deployment — Step-by-step frontend build and deploy procedure
- Nakama Deployment — Building and deploying Nakama TypeScript runtime modules
- Secrets Management — Operational keys and database credentials runbook
- Wiki Update — Procedure for updating and rebuilding Quartz documentation
Related
Architecture and system details related to operational procedures.