From 62f1c4d9fc5a1ed125da978ffe6e1b175bcad409 Mon Sep 17 00:00:00 2001 From: SimpleTest Date: Sat, 25 Jul 2026 16:46:45 +0300 Subject: [PATCH] Document verifiable public launch readiness --- README.md | 4 +- docs/operations.md | 4 ++ docs/public-launch-checklist.md | 116 ++++++++++++++++++++++++++++++++ docs/verification.md | 6 ++ 4 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 docs/public-launch-checklist.md diff --git a/README.md b/README.md index 2a64dd5..40669e1 100644 --- a/README.md +++ b/README.md @@ -235,7 +235,9 @@ presented as an FCM or APNs implementation; an external provider must resolve the stable user recipient to registered devices. The commands, boundaries, and unclaimed production properties are documented -in [the operations runbook](docs/operations.md). +in [the operations runbook](docs/operations.md). Use the +[public launch checklist](docs/public-launch-checklist.md) to keep automated +evidence separate from provider, staffing, and jurisdiction-specific approvals. Local defaults are intentionally limited to local development. Copy `.env.example` to `.env` and replace every secret before any public deployment. diff --git a/docs/operations.md b/docs/operations.md index b175c89..07e7f33 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -216,6 +216,10 @@ Check an environment without printing its secret values: ./scripts/check-environment-readiness.sh .env --require-release ``` +The complete promotion sequence and the human/provider decisions that these +scripts cannot prove are listed in +[`docs/public-launch-checklist.md`](public-launch-checklist.md). + Provider downloads can be imported into that same file without placing secrets on a command line or printing them: diff --git a/docs/public-launch-checklist.md b/docs/public-launch-checklist.md new file mode 100644 index 0000000..899cfdb --- /dev/null +++ b/docs/public-launch-checklist.md @@ -0,0 +1,116 @@ +# Public launch checklist + +This checklist separates properties the repository can verify from decisions +that require the operator, a provider, or jurisdiction-specific legal review. +Checking a box is an operator record, not proof created by the application. +Do not replace unknown values with estimates. + +## 1. Freeze the candidate + +- [ ] Record the candidate Git revision and immutable application, PostGIS, + socket-proxy, and edge image references. +- [ ] Confirm that the target is the independent production checkout, Compose + project, database, volumes, secrets, Google/Firebase project, SMTP + credentials, and Android identity. +- [ ] Keep development, hackathon test, and production credentials separate. +- [ ] Run the repository quality suite and retain its non-secret evidence. + +```bash +git rev-parse HEAD +./scripts/quality.sh +``` + +## 2. Verify production configuration without exposing secrets + +Run both checks against the single ignored production `.env`. The first reports +capabilities; the second additionally enforces the repository's release +requirements. + +```bash +./scripts/validate-production-env.sh .env whoneedhelp.com +./scripts/check-environment-readiness.sh .env --require-release +``` + +The release check covers the application origin and secrets, database +selection, SMTP and support routing, Google OAuth, browser VAPID, Firebase/FCM, +Android package/signing configuration, and production App Links. It does not +prove that external providers will deliver successfully after deployment. + +## 3. Record human and legal decisions + +The following decisions are intentionally not generated by code: + +- [ ] Launch jurisdictions and the exact local emergency contacts shown to + users have been approved. +- [ ] Privacy notice, Terms, medicine/prohibited-items guidance, and voluntary + payment/reimbursement wording have been reviewed for those jurisdictions. +- [ ] A retention and anonymisation schedule defines each account, safety, + dispute, moderation, support, legal, tracking-evidence, and backup record. +- [ ] The account-deletion executor and operator procedure have been approved + and tested against that schedule before destructive execution is enabled. +- [ ] Moderation, support, privacy, account-deletion, content-removal, and + incident queues have named owners and monitored contact paths. +- [ ] Provider terms and capacity are approved for email, map tiles, Google + identity, Web Push, Firebase/FCM, database hosting, backups, and monitoring. +- [ ] Representative load measurements from the intended host and traffic shape + justify database pools, action-limit policies, replica counts, memory/CPU + allocation, alerts, and any scaling thresholds. +- [ ] Backup ownership, encryption-key custody, off-site destination, restore + procedure, and measured recovery objectives have been approved. + +Until the retention decision and tested executor exist, account-deletion cases +remain an audited operator workflow and automatic erasure stays disabled. The +software must not claim that an unresolved legal or operational item is +complete. + +## 4. Rehearse recovery before promotion + +Create a current custom-format backup and restore it only into the isolated +drill database. Then rehearse the current release against that backup. + +```bash +backup_output=$(./scripts/backup-compose.sh) +backup_path=$(printf '%s\n' "$backup_output" | sed -n 's/^Backup: //p') +./scripts/restore-drill-compose.sh "$backup_path" +./scripts/upgrade-rehearsal-compose.sh "$backup_path" +./scripts/production-rollback-drill.sh +``` + +Local backups and local MinIO drills verify mechanics but are not proof of +off-site durability or a production recovery policy. + +## 5. Promote with an explicit rollback point + +Use the release workflow in `docs/operations.md`; do not copy mutable source +over a running production checkout. A successful release must retain the +generated rollback manifest, the pre-release backup checksum/catalog, and the +previous immutable image references. A forward-only migration must be treated +as forward-only rather than receiving an invented database rollback. + +## 6. Verify the deployed product + +- [ ] Public HTTPS home, liveness, readiness, WebSocket upgrade, manifest, and + `assetlinks.json` return the expected production identity. +- [ ] Registration, returning-user login, and settings linking complete against + the production Google OAuth client and exact callback origin. +- [ ] A production-generated authentication email reaches an external mailbox; + sender identity and every URL use the production domain. +- [ ] Browser Web Push reaches a real subscribed browser. +- [ ] The production Android build signs in, opens verified App Links, receives + FCM, and performs user-started foreground location sharing on a physical + device. +- [ ] The full two-person help flow passes: create, discover, accept, chat, + optional tracking, start, handover code, both confirmations, blind review, + report/block, and notification delivery. +- [ ] The Activity flow passes: create, request to join, approve/decline, + withdraw, rejoin, group chat, exact-location disclosure only after + approval, and reporting. +- [ ] Support, privacy/data, account-deletion, general content-removal, and + TAKE IT DOWN submissions reach the correct production operator queues. +- [ ] Database, application, worker, email, push, backup, and edge monitoring + are visible to the responsible operator. + +Record observed timestamps, revision/image identities, and non-secret evidence +paths in `docs/verification.md`. Record failed checks as failed; do not convert +them into documentation-only success. + diff --git a/docs/verification.md b/docs/verification.md index 758504f..936a1ee 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -1611,6 +1611,12 @@ None of the observations below describe the current delivery path. ## Known work before a public production launch +The operator-facing sequence is maintained in +[`docs/public-launch-checklist.md`](public-launch-checklist.md). That checklist +separates repository-verifiable evidence from external provider, staffing, and +jurisdiction-specific decisions; an unchecked or unknown item is not claimed +complete. + - Promote the tested release from `test.whoneedhelp.com` to the independent production project only after explicit approval. Recheck the production health endpoints, migrations, Google callback, and authentication-email flow