Skip to content

deploy.md

Latest commit

 

History

History
105 lines (83 loc) · 5.32 KB

deploy.md

File metadata and controls

105 lines (83 loc) · 5.32 KB

Deploy runbook — pixieengine.com static archive

Steps to take the generated static tree live on pixieengine.com. Plan: a greenfield AWS CDK stack (infra/, PixieStaticStack) stands up a new private S3 bucket + new CloudFront distribution + edge function. The legacy distribution E3BKYYG8EH9O0K is never touched. Cutover = move the pixieengine.com DNS alias to the new distribution; rollback = move it back. Companion to architecture.md; the canonical infra-as-code runbook is ../infra/README.md.

(Historical note: an earlier draft of this doc repointed E3BKYYG8EH9O0K's origin in place. That approach is superseded by the greenfield stack below — it's safer, fully reversible via DNS, and keeps the live distribution untouched until verification passes.)

Pieces (all created by the CDK stack in infra/)

  • New distribution: a fresh CloudFront distribution (separate from E3BKYYG8EH9O0K). index.html root object; 403/404 → /410/index.html served as 404 (CloudFront can't emit a 410 in custom-error responses); rewrite function on viewer-request.
  • New bucket: pixieengine-static — private, CloudFront OAC only, RETAIN removal policy.
  • Edge function: pixieengine-rewrite (infra/functions/rewrite.js; id/slug rewrite, ?tagged=→/tags/ 301, dir→index). Unit-tested via npm test in infra/.
  • Custom domain (cutover only, -c withDomain=true): ACM cert (DNS-validated in zone ZPF3QICRGSLCF) + pixieengine.com alias + Route 53 A/AAAA → new dist.
  • Deploy IAM user: pixieengine-deploy (scoped — policy in aws-inventory.md): rw on the bucket + cloudfront:CreateInvalidation. The stack grants it read/write on pixieengine-static.

The initial upload used a hand-made staging bucket pixieengine-com-site (256,530 objects), server-side-copied into pixieengine-static. That bucket was deleted 2026-06-02; deploys now sync directly from ../static-site/public (below).

Prereqs

  • cdk deploy needs admin creds → run from AWS CloudShell (uses the console admin/root identity, no local keys). cdk synth/diff, npm test, and aws s3 sync run fine locally with the scoped profiles (pixieengine-deploy rw, pixieengine-audit read-only).
  • infra/ is self-contained (includes functions/rewrite.js). Get it into CloudShell via git push + clone, or upload a zip.

A. Sanity-check locally (no creds)

cd ~/apps/pixieengine.com/infra
npm install
npm test            # rewrite-function unit tests (16 assertions)
npx cdk synth       # confirms the stack compiles to a valid template

B. Phase 1 — deploy the new stack (no alias; invisible to the live domain)

In CloudShell:

cd infra && npm install
npx cdk bootstrap aws://186123361267/us-east-1   # once per account/region
npx cdk deploy                                    # creates bucket + dist + function; alias NOT attached

Note the DistributionId and DistributionDomain (dXXXX.cloudfront.net) outputs.

C. Populate + invalidate

Content is not managed by CDK (it's a deploy step). Sync the generated tree from local:

aws s3 sync ../static-site/public s3://pixieengine-static --delete --profile pixieengine-deploy
aws cloudfront create-invalidation --distribution-id <DistributionId> --paths "/*"

D. Verify on the dXXXX.cloudfront.net URL (before cutover)

  • https://dXXXX.cloudfront.net/ → editor shell (200); /sprites/ → gallery; /sprites/page/100/ → logarithmic pager.
  • /sprites/257680-ugly-killman-donkey-ass → sprite page (slug variant 200).
  • /sprites?tagged=mario → 301 → /tags/mario/.
  • A missing id (e.g. /sprites/999999999) → 404 (the /410/index.html gone page).
  • /sitemap.xml → 200.
  • A sprite with a replay → ▶ Watch replay plays in the editor.
  • A tune → ▶ Play in Composer loads in the composer.

E. Phase 2 — cutover (the only step that touches the live domain)

A CloudFront alias can live on only one distribution. So, only after verification passes:

  1. Remove the pixieengine.com alias (CNAME) from the legacy dist E3BKYYG8EH9O0K (console).
  2. Add it to the new dist + create cert + DNS: 
    npx cdk deploy -c withDomain=true     # ACM cert, alias, Route 53 A/AAAA -> new dist
    (ACM DNS validation auto-creates a CNAME in the zone; the first deploy waits for it.)
  3. Verify https://pixieengine.com/ (rerun the section-D checklist on the apex domain).

Rollback

Re-point the pixieengine.com Route 53 alias back to the legacy dist E3BKYYG8EH9O0K (or re-add the alias there). Nothing in the legacy distribution was modified, so rollback is pure DNS.

Ongoing content deploys

aws s3 sync ../static-site/public s3://pixieengine-static --delete --profile pixieengine-deploy
aws cloudfront create-invalidation --distribution-id <DistributionId> --paths "/*" --profile pixieengine-deploy

Incremental regen (enriched titles, etc.) → re-generate → s3 sync → invalidate just the changed paths. Full tree is ~256k objects.

Notes

  • Content-types are inferred from extensions (.html→text/html, .css→text/css, .xml→application/xml).
  • After launch: delete the temporary pixieengine-audit user. (The staging bucket pixieengine-com-site was deleted 2026-06-02.)