Runbook: Devbox

Synced read-only from /home/synnet/synvirt-platform/docs-internal/runbooks/devbox.md. Edit at the source, not here.

Runbook: Devbox

Provision a fresh box

git clone <ssh-remote> synvirt-platform && cd synvirt-platform
bash infra/scripts/devbox-bootstrap.sh   # idempotent
# log out/in if it added you to the docker group (skip if running as root)
cp .env.example .env                      # fill in change_me values
task secrets:decrypt                      # OR keep the hand-edited .env
task up
task trust-ca   # only for *.synvirt.test — *.synvirt.mx uses Let's Encrypt (DNS-01)
task migrate

Daily

Action	Command
Start infra	task up
Stop (keep data)	task down
Status	task ps
Logs (one svc)	task logs -- keycloak
psql shell	task psql -- portal
New migration	task migrate-new -- add_subscriptions
Run app (API)	task dev:api
Run app (web)	task dev:web
Reset everything	task nuke (deletes volumes)

Verify Phase 0 acceptance

# 4 databases with owner roles
task psql -- portal -c '\l'        # expect portal, payload, keycloak, discourse

# Keycloak reachable with trusted CA (no TLS warning)
curl -sS https://auth.synvirt.test/realms/synvirt/.well-known/openid-configuration | jq .issuer

# Portal API health (after `task dev:api`)
curl -sS https://api.synvirt.test/health

Gotchas

• host.docker.internal is wired for Caddy via extra_hosts in compose.dev.yaml (Linux needs this; it is not automatic).
• DB ports are published only on 127.0.0.1 in dev so host apps can connect; they are never published in prod.
• Keycloak runs start-dev in dev. Prod needs a built/optimized image (kc.sh build) — added in M1/M8.
• Keycloak realm JSON rejects unknown fields. Do NOT add _comment (or any non-schema key) to infra/keycloak/realm-synvirt.json; the importer fails with Unrecognized field ... not marked as ignorable and the container crash-loops. Put notes in code/docs, not the realm file.
• CA trust: after task trust-ca, also import /tmp/synvirt-ca.crt into the browser’s trust store.
• pnpm 11 supply-chain cooldown. pnpm 11 enforces a default minimumReleaseAge and rejects dependencies published too recently (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION). This is a feature we keep (supply-chain defense). If a needed package is brand new, pin to a slightly older version, or set minimumReleaseAge/ minimumReleaseAgeExclude in pnpm-workspace.yaml deliberately. Non-interactive installs that migrate node_modules need CI=true (no-TTY purge confirmation).