buckyverse.org Cutover Runbook (Wiki.js -> Astro)

Execute in order. Agent-built pieces (redirect map + verifier) are done and deployed
to future.buckyverse.org. Steps below are the production, human-executed cutover.

Redirect mechanism (important): Cloudflare Pages _redirects has a hard
100-rule cap (rules past #100 are silently dropped). So the redirect map is
split: the ~19 pattern rules (dictionary, knowledge /en, synergetics,
orphan→home prefixes) ship in apps/reader/public/_redirects and fire now on
future.buckyverse.org; the ~196 precise per-book rules
(/<book_dir> → /read/<slug>, WDSD docs, non-readable → /library) live in
dev/cloudflare/cutover-bulk-redirects.csv and must be imported as a Cloudflare
Bulk Redirects list (Phase 1b) before they fire.

Phase 0 — pre-flight (DONE by agent, confirm)

• future.buckyverse.org has full parity (SP1-5).
• SP3 dictionary image R2 upload finished — all 21,193 uploaded, 0 failed (2026-07-06); no card-image 404s.
• pnpm --filter reader verify-redirects https://future.buckyverse.org prints "All checks passed." (Pattern rules + content-serving; per-book rules verified in Phase 3 after the bulk import — Phase 1b done.)

Phase 1 — add custom domains (Cloudflare dashboard)

• Pages -> buckyverse-future -> Custom domains -> add buckyverse.org and www.buckyverse.org.
• Wait for TLS "Active". Note the DNS target Cloudflare shows.

Phase 1b — import the per-book Bulk Redirects list ✅ DONE 2026-07-06

Imported via import-bulk-redirects.sh: account list buckyverse_wikijs_book_redirects
(84e12414107f4a74b537a30a6983cace), 196 items, rule attached to the
http_request_redirect phase. It fires once buckyverse.org routes through
Cloudflare (after Phase 2). Verify in Phase 3.

• Regenerate if the book set changed: pnpm --filter reader bulk-redirects → dev/cloudflare/cutover-bulk-redirects.csv.
• Automated (recommended): run the API script — creates the list, uploads the ~196 items, waits for the operation, and attaches the redirect rule (merging into the phase, so existing rules are kept):

  dev/cloudflare/import-bulk-redirects.sh --dry-run   # sanity-check the CSV parse first
  CF_API_TOKEN=<token> CF_ACCOUNT_ID=3285a9244297dfb464e93966e454e2ea \
    dev/cloudflare/import-bulk-redirects.sh
  

  Token needs ACCOUNT permissions Account Filter Lists: Edit + Account Rulesets: Edit. Idempotent (safe to re-run). Requires jq.
• Manual (dashboard alternative): Account Home → Bulk Redirects → create a Redirect List → Upload CSV (cutover-bulk-redirects.csv) → create a Bulk Redirect rule referencing the list.
• (Account-level; applies once the apex serves through Cloudflare — Option A. Under Option B the redirects must target the www host.)

Phase 2 — DNS (Route 53) — pick ONE apex option

Option A (recommended): move the buckyverse.org zone to Cloudflare

• Add the zone in Cloudflare; recreate ALL existing records (graph, future, MX, TXT, etc.).
• At the registrar, change nameservers to Cloudflare's. (Propagation up to 24-48h.)
• In Cloudflare DNS: apex buckyverse.org and www -> the Pages project (CNAME/flattening, per the Custom-domains panel).

Option B: keep Route 53

• www.buckyverse.org CNAME -> buckyverse-future.pages.dev (canonical host).
• apex buckyverse.org -> redirect to https://www.buckyverse.org (S3 website redirect bucket + Route 53 alias, or a Cloudflare redirect). Route 53 cannot CNAME an apex to pages.dev.

Phase 3 — verify in production

• curl -sI https://buckyverse.org/ -> 200, server: cloudflare.
• pnpm --filter reader verify-redirects https://buckyverse.org -> "All checks passed." (pattern rules + content)
• Per-book (bulk) redirects fired: curl -sI https://buckyverse.org/grunch_of_giants -> 301 -> /read/grunch_of_giants; curl -sI https://buckyverse.org/world_design_science_decade_1965-1975/document-2-the-design-initiative -> 301 -> /read/wdsd_2_the_design_initiative. (If these 200 instead of 301, the Bulk Redirects list/rule from Phase 1b isn't active yet.)
• Manual spot-check: a dictionary card, a knowledge article, a book page, /library.

Phase 4 — rollback window (default 7 days)

• Leave the droplet (64.23.238.243) + Wiki.js Postgres RUNNING and untouched.
• Rollback if needed = revert apex/www DNS to the droplet (Option A: change Cloudflare records; Option B: restore Route 53). Instant; no data reconciliation.

Phase 5 — retire (after the window)

• Final backup: snapshot the droplet AND pg_dump the Wiki.js DB to cold storage.
• Destroy the droplet; stop the Wiki.js docker-compose.
• Remove dead DNS (do.buckyverse.org and any droplet A records).
• Archive dev/wikijs/ scripts as historical (the GraphQL push/projector tooling is no longer needed).

Migration complete: buckyverse.org IS the Astro site.