Deployment Preflight Runbook

This runbook turns the roadmap's deployment-foundation work into a repeatable launch-readiness check. It does not replace the Era C exit gate; it verifies that the deployed environment is ready to start collecting trustworthy staging or production evidence.

Commands

Controlled public beta / staging rehearsal:

pnpm launch:preflight

Production launch review:

pnpm launch:preflight:production

Artifacts:

• `artifacts/launch/deployment-preflight-latest.json`
• `artifacts/launch/runs/deployment-preflight-<timestamp>.json`

The preflight, storage export, DR drill, launch review, and staging explore-smoke scripts load local `.env*` files for operator convenience, but explicit shell or CI environment variables always win.

What It Checks

• Storage resolves to Postgres-backed mode via `DATABASE_URL` and `METAMUSEUM_STORAGE_MODE`.
• Database SSL mode is pinned to `sslmode=verify-full`; staging warns on `require`/missing values, and production fails until full verification is explicit.
• Auth.js launch secrets are present and not using the development fallback.
• GitHub OAuth credentials are present for sign-in; failures name the exact missing variable without exposing secret values.
• Public base URL is configured for smoke, uptime, and SLO commands.
• Public-read uptime source is configured through Prometheus or scheduled probes.
• k6 has a real deployed target and an explicit `IIIF_TILE_URL` for launch SLO evidence.
• Latest DR drill artifact is fresh and has a verified Postgres restore rehearsal.
• Test-role override secrets are available for staging smoke, pass a basic secret-quality check, and are absent from production.

Required Environment Surface

Minimum public-beta/prod variables:

• `DATABASE_URL` with `sslmode=verify-full`
• `METAMUSEUM_STORAGE_MODE=postgres`
• `AUTH_SECRET`
• `AUTH_GITHUB_ID`
• `AUTH_GITHUB_SECRET`
• `BASE_URL` or `METAMUSEUM_PUBLIC_READ_BASE_URL`
• `METAMUSEUM_UPTIME_PROMETHEUS_URL` or scheduled probe config via `METAMUSEUM_PUBLIC_READ_BASE_URL`
• `IIIF_TILE_URL`

Staging-only smoke support:

• `METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN` (generated by `pnpm launch:smoke-token`; same value on server and smoke runner)

Launch Review Sequence

1. Configure the deployed environment and secrets.

1. For staging, run `pnpm launch:smoke-token` once per token rotation; it updates local `.env` without printing the value, so copy `METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN` from the env file into both the staging server and smoke runner.

1. Run `pnpm storage:export:postgres` after setting `DATABASE_URL`; the exporter uses the same managed-document contract as `src/utils/storage.ts`.

1. Run `pnpm dr:drill` against the configured storage mode.

1. Run `pnpm launch:preflight` or `pnpm launch:preflight:production`.

1. Run public smoke checks:

1. Collect performance and exit-gate evidence:

1. Generate the launch decision packet:

• `BASE_URL=https://<deploy-host> pnpm smoke:public-trust`
• `BASE_URL=https://<deploy-host> pnpm a11y:check` writes `artifacts/launch/a11y-latest.json`.
• `BASE_URL=https://<deploy-host> pnpm smoke:explore:matrix` writes `artifacts/launch/explore-smoke-latest.json` for staging researcher flow.
• `BASE_URL=https://<deploy-host> IIIF_TILE_URL=https://<iiif-tile> pnpm k6:slo`
• `pnpm era-c:exit-gate:evidence`
• `pnpm launch:review` for controlled beta / staging.
• `pnpm launch:beta:readiness` for the controlled beta go/no-go summary.
• `pnpm launch:review:production` for fail-fast production review.

Pass Criteria

• Staging can proceed with warnings only when the warnings are explicitly accepted for rehearsal.
• Production must have `status: "pass"` in `deployment-preflight-latest.json`.
• Passing deployment preflight means the environment is ready to collect evidence; it does not mean the 30-day SLO, uptime, adoption, or KPI gates have passed.
• Passing launch review requires fresh launch evidence across preflight, exit-gate, hardening, smoke, a11y, and explore import checks; see `docs/ops/launch-review.md`.
• Passing controlled beta readiness means staging can go live with only accepted evidence-collection warnings; production still requires `pnpm launch:review:production`.