Production Deployment Handbook (Cloudflare Workers)
Complete production architecture, Neon + Hyperdrive setup, R2 media buckets, Cloudflare Queues, Worker secrets, GitHub environment isolation, and rollback runbook.
Production deployments are triggered manually via the Deploy Production Cloudflare GitHub Actions workflow (.github/workflows/deploy-production-cloudflare.yml). Before building or deploying, the deploy job executes a read-only migration gate (server/scripts/check-pending-migrations.ts): if any unapplied database migrations exist, the deployment halts and instructs the operator to run operation=migrate first.
1. Confirmed Architectural Decisions (2026-11-10)
| Item | Decision |
|---|---|
| Cloudflare Account | Exclusively use the zsg account fb5cf2a97e781c3547aca30e67cc225d (never personal accounts). |
| Neon PostgreSQL | Qi Fang organization (org-divine-math-41972526); production project in aws-us-east-1; PostgreSQL 17 with 7-day PITR enabled and scale-to-zero disabled. |
| Database Roles | Least-privilege application role slloy_app (DML + sequences only, zero DDL permissions); schema migrations use slloy_com_owner. |
| Hyperdrive Caching | --caching-disabled on both production and staging (query caching without write-invalidation cannot be used for credits, sessions, or orders). |
index.html Routing | /index.html and /<path>/index.html return 301; .html paths carrying query strings (unless matched in legacy-redirects.csv) return 404. |
| HSTS | Sent by Hono's securityHeaders middleware on slloy.com (max-age=31536000); never enabled at the Cloudflare zone level so staging is unaffected. |
| Storage Timeout | STORAGE_TIMEOUT_MS=120000 (120s), matching code default so video R2 persistence does not silently time out at 30s. |
2. Production Resource Inventory
| Resource | Name | Identifier / Notes |
|---|---|---|
| Neon Project | slloy-production | nameless-lab-96517142 (aws-us-east-1, PostgreSQL 17) |
| Neon Main Branch | main | br-royal-butterfly-bb5t40jm, database slloy_com |
| Hyperdrive (Prod) | slloy-production-neon | 8f3ade3abbc840a0945e039c824fe8d8 (caching disabled) |
| R2 Media Bucket | slloy-production-uploads | Private bucket; served exclusively through Worker /uploads/* with Range support |
| R2 Backup Bucket | slloy-production-uploads-backup | Append-only incremental backup synced daily at 02:10 CST via R2 Backup workflow |
| Image Queue / DLQ | slloy-production-images / -dlq | Async image generation (max_batch_size=1, max_retries=3, then routes to -dlq) |
| Production Worker | slloy-production-api | wrangler.jsonc env.production (hosts Hono API, static assets, Cron, Queue consumer, and /prompts TanStack Start SSR) |
| Production Routes | slloy.com/*, www.slloy.com/* | Bound to slloy-production-api; www is 301 redirected to apex by forceApexHost middleware |
3. Database Provisioning (Neon + Hyperdrive)
- Create Neon Project (
slloy-production):neon projects create --name slloy-production --org-id org-divine-math-41972526 \ --region-id aws-us-east-1 --pg-version 17 --database slloy_com --role slloy_com_owner - Explicit ICU Collation (
en-US):DROP DATABASE slloy_com; CREATE DATABASE slloy_com WITH OWNER = slloy_com_owner TEMPLATE = template0 ENCODING = 'UTF8' LOCALE_PROVIDER = icu ICU_LOCALE = 'en-US' LC_COLLATE = 'C.UTF-8' LC_CTYPE = 'C.UTF-8'; - Create Least-Privilege Application Role (
slloy_app):CREATE ROLE slloy_app LOGIN PASSWORD '<generated-by-password-manager>'; GRANT CONNECT ON DATABASE slloy_com TO slloy_app; GRANT USAGE ON SCHEMA public TO slloy_app; GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO slloy_app; GRANT USAGE, SELECT, UPDATE ON ALL SEQUENCES IN SCHEMA public TO slloy_app; ALTER DEFAULT PRIVILEGES FOR ROLE slloy_com_owner IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO slloy_app; ALTER DEFAULT PRIVILEGES FOR ROLE slloy_com_owner IN SCHEMA public GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO slloy_app; - Create Hyperdrive Config (
--caching-disabled, Direct Hostname): Must use Neon's direct hostname (without-pooler):npx wrangler hyperdrive create slloy-production-neon \ --connection-string="postgresql://slloy_app:<password>@<neon-direct-host>/slloy_com?sslmode=require" \ --caching-disabled - Enable 7-Day PITR Window (
604,800Seconds):neon api /projects/nameless-lab-96517142 -X PATCH -F project.history_retention_seconds=604800 - Pre-Release Migration & Integrity Audit:
Run
server/scripts/migrate-postgres.ts --applyandserver/scripts/audit-user-integrity.ts.
4. R2 Storage & Cloudflare Queues
R2 Buckets
npx wrangler r2 bucket create slloy-production-uploads
npx wrangler r2 bucket create slloy-production-uploads-backupCloudflare Queues (IMAGE_QUEUE)
wrangler deploy will refuse to deploy if the queues do not exist:
npx wrangler queues create slloy-production-images
npx wrangler queues create slloy-production-images-dlqTemporary reference images (_refs/) are deleted upon terminal job consumption, and any orphaned _refs/ objects older than 1 hour are cleaned up by the 5-minute Cron (sweepRefImages).
5. Worker Secrets & GitHub production Environment
Required Worker Secrets (--env production)
Production is defined under env.production in wrangler.jsonc. Always pass -c wrangler.jsonc --env production when uploading secrets (omitting --env writes to the top-level staging Worker!). server/scripts/check-production-secrets.ts verifies that all 8 required secrets are present before deployment:
npx wrangler secret put ADMIN_JWT_SECRET -c wrangler.jsonc --env production
npx wrangler secret put BETTER_AUTH_SECRET -c wrangler.jsonc --env production
npx wrangler secret put RESEND_API_KEY -c wrangler.jsonc --env production
npx wrangler secret put ARK_API_KEY -c wrangler.jsonc --env production
npx wrangler secret put DASHSCOPE_API_KEY -c wrangler.jsonc --env production
npx wrangler secret put KLING_API_KEY -c wrangler.jsonc --env production
npx wrangler secret put STRIPE_SECRET_KEY -c wrangler.jsonc --env production
npx wrangler secret put STRIPE_WEBHOOK_SECRET -c wrangler.jsonc --env productionOptional Admin Access verification secrets (ADMIN_ACCESS_TEAM_DOMAIN, ADMIN_ACCESS_AUD):
npx wrangler secret put ADMIN_ACCESS_TEAM_DOMAIN -c wrangler.jsonc --env production
npx wrangler secret put ADMIN_ACCESS_AUD -c wrangler.jsonc --env productionGitHub production Environment Secrets
All production deploy, migration, backup, and ops jobs declare environment: production (restricted to refs/heads/main, with zero repository-level fallback copies):
NEON_DATABASE_URL: Direct connection string forslloy_com_owneronslloy_com(migration job assertscurrent_database() === 'slloy_com'before executing).CLOUDFLARE_API_TOKEN&CLOUDFLARE_ACCOUNT_IDR2_ACCESS_KEY_ID&R2_SECRET_ACCESS_KEY: R2 S3-compatible credentials (32-char Key ID + 64-char Secret Key; neverCFAT_account tokens).
6. Version Rollback
npm run build:web
CLOUDFLARE_ENV=production npm run build:worker
npm run check:wrangler -- --expect-target production
npx wrangler rollback --env production --yes[!WARNING]
wrangler rollbackonly rolls back the Worker code version. It does not roll back Neon PostgreSQL data or R2 media objects. For database PITR and R2 recovery, see Backup & Disaster Recovery.
Cloudflare Access Zero Trust & Edge JWT Isolation
Dual-layer Cloudflare Access architecture (Zero Trust edge gate + Worker RS256 JWT verification) protecting staging.slloy.com, /admin, and docs.slloy.com.
Staging Environment & Local Development
Staging Cloudflare Worker architecture, build order (build:web -> build:worker), Cloudflare Access Service Token smoke verification, Stripe sandbox, and QA tools.