{"id":"ops/deployment-preflight","relativePath":"ops/deployment-preflight.md","title":"Deployment Preflight Runbook","markdown":"# Deployment Preflight Runbook\n\nThis 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.\n\n## Commands\n\nControlled public beta / staging rehearsal:\n\n```bash\npnpm launch:preflight\n```\n\nProduction launch review:\n\n```bash\npnpm launch:preflight:production\n```\n\nArtifacts:\n\n- `artifacts/launch/deployment-preflight-latest.json`\n- `artifacts/launch/runs/deployment-preflight-.json`\n\nThe 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.\n\n## What It Checks\n\n- Storage resolves to Postgres-backed mode via `DATABASE_URL` and `METAMUSEUM_STORAGE_MODE`.\n- Database SSL mode is pinned to `sslmode=verify-full`; staging warns on `require`/missing values, and production fails until full verification is explicit.\n- Auth.js launch secrets are present and not using the development fallback.\n- GitHub OAuth credentials are present for sign-in; failures name the exact missing variable without exposing secret values.\n- Public base URL is configured for smoke, uptime, and SLO commands.\n- Public-read uptime source is configured through Prometheus or scheduled probes.\n- k6 has a real deployed target and an explicit `IIIF_TILE_URL` for launch SLO evidence.\n- Latest DR drill artifact is fresh and has a verified Postgres restore rehearsal.\n- Test-role override secrets are available for staging smoke, pass a basic secret-quality check, and are absent from production.\n\n## Required Environment Surface\n\nMinimum public-beta/prod variables:\n\n- `DATABASE_URL` with `sslmode=verify-full`\n- `METAMUSEUM_STORAGE_MODE=postgres`\n- `AUTH_SECRET`\n- `AUTH_GITHUB_ID`\n- `AUTH_GITHUB_SECRET`\n- `BASE_URL` or `METAMUSEUM_PUBLIC_READ_BASE_URL`\n- `METAMUSEUM_UPTIME_PROMETHEUS_URL` or scheduled probe config via `METAMUSEUM_PUBLIC_READ_BASE_URL`\n- `IIIF_TILE_URL`\n\nStaging-only smoke support:\n\n- `METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN` (generated by `pnpm launch:smoke-token`; same value on server and smoke runner)\n\n## Launch Review Sequence\n\n1. Configure the deployed environment and secrets.\n2. 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.\n3. Run `pnpm storage:export:postgres` after setting `DATABASE_URL`; the exporter uses the same managed-document contract as `src/utils/storage.ts`.\n4. Run `pnpm dr:drill` against the configured storage mode.\n5. Run `pnpm launch:preflight` or `pnpm launch:preflight:production`.\n6. Run public smoke checks:\n - `BASE_URL=https:// pnpm smoke:public-trust`\n - `BASE_URL=https:// pnpm a11y:check` writes `artifacts/launch/a11y-latest.json`.\n - `BASE_URL=https:// pnpm smoke:explore:matrix` writes `artifacts/launch/explore-smoke-latest.json` for staging researcher flow.\n7. Collect performance and exit-gate evidence:\n - `BASE_URL=https:// IIIF_TILE_URL=https:// pnpm k6:slo`\n - `pnpm era-c:exit-gate:evidence`\n8. Generate the launch decision packet:\n - `pnpm launch:review` for controlled beta / staging.\n - `pnpm launch:beta:readiness` for the controlled beta go/no-go summary.\n - `pnpm launch:review:production` for fail-fast production review.\n\n## Pass Criteria\n\n- Staging can proceed with warnings only when the warnings are explicitly accepted for rehearsal.\n- Production must have `status: \"pass\"` in `deployment-preflight-latest.json`.\n- 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.\n- Passing launch review requires fresh launch evidence across preflight, exit-gate, hardening, smoke, a11y, and explore import checks; see `docs/ops/launch-review.md`.\n- Passing controlled beta readiness means staging can go live with only accepted evidence-collection warnings; production still requires `pnpm launch:review:production`.\n","sections":[{"level":2,"heading":"Commands","anchor":"commands"},{"level":2,"heading":"What It Checks","anchor":"what-it-checks"},{"level":2,"heading":"Required Environment Surface","anchor":"required-environment-surface"},{"level":2,"heading":"Launch Review Sequence","anchor":"launch-review-sequence"},{"level":2,"heading":"Pass Criteria","anchor":"pass-criteria"}],"html":"

Deployment Preflight Runbook

\n

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.

\n

Commands

\n

Controlled public beta / staging rehearsal:

\n
\npnpm launch:preflight\n
\n

Production launch review:

\n
\npnpm launch:preflight:production\n
\n

Artifacts:

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

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.

\n

What It Checks

\n
  • 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.
\n

Required Environment Surface

\n

Minimum public-beta/prod variables:

\n
  • `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`
\n

Staging-only smoke support:

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

Launch Review Sequence

\n
  1. Configure the deployed environment and secrets.
\n
  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.
\n
  1. Run `pnpm storage:export:postgres` after setting `DATABASE_URL`; the exporter uses the same managed-document contract as `src/utils/storage.ts`.
\n
  1. Run `pnpm dr:drill` against the configured storage mode.
\n
  1. Run `pnpm launch:preflight` or `pnpm launch:preflight:production`.
\n
  1. Run public smoke checks:
\n
  1. Collect performance and exit-gate evidence:
\n
  1. Generate the launch decision packet:
\n
  • `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.
\n

Pass Criteria

\n
  • 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`.
","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"ac60432d0aed72aa09e29dc5b89cf5423aeb625708973019ee9fd5d1a692838f","checksumPrefix":"ac60432d0aed","anchorCount":5,"lineCount":81,"rawUrl":"/api/docs/content?path=ops%2Fdeployment-preflight.md","htmlUrl":"/docs?doc=ops%2Fdeployment-preflight.md","apiUrl":"/api/docs/content?path=ops%2Fdeployment-preflight.md"}