Skip to Content
Slloy Docs
Operations, Deployment & DR

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.

Staging runs entirely on Cloudflare Workers (slloy-staging-api at https://staging.slloy.com), backed by Neon PostgreSQL 17 (slloy_staging via Hyperdrive slloy-staging-neon), Cloudflare R2 (slloy-staging-uploads), and Cloudflare Queues (slloy-staging-images / -dlq).

1. Dual-Target wrangler.jsonc & Build Pipeline

A single wrangler.jsonc defines both targets: the top-level configuration is staging (slloy-staging-api), and env.production is production (slloy-production-api). Because bindings (vars, hyperdrive, r2_buckets, queues) do not inherit across environments in Wrangler, every environment block declares its full set of bindings explicitly.

Mandatory Build Sequence (build:web -> build:worker)

  1. npm run build:web:
    • Builds the pre-rendered static site, /admin SPA, and share scripts into dist/.
    • Compresses the runtime content required for /prompts SSR (articles, dictionaries, page metadata) into dist/_worker/content/. The Worker reads this JSON via the ASSETS binding at runtime rather than bundling megabytes of content into the Worker script (/_worker/* returns 404 to external requests).
  2. npm run build:worker (with CLOUDFLARE_ENV=staging or production):
    • @cloudflare/vite-plugin compiles the SSR Worker into .worker-dist/ssr/wrangler.json and points .wrangler/deploy/config.json to it.
    • At the end of build:worker, tools/worker-assets.ts rewrites assets.directory in the generated config back to dist/ while keeping .worker-dist/client so npm run check:wrangler can verify asset hash consistency.
  3. npm run check:wrangler -- --expect-target staging:
    • Verifies that dist/_worker/content/ exists, article bodies are not bundled inside the JS script, uncompressed Worker size is within the 7,168 KiB budget (WORKER_BUDGET_KIB), and targetEnvironment matches.
  4. Deployment (npx wrangler deploy):
    • Never run wrangler deploy -c wrangler.jsonc directly against source (esbuild cannot resolve TanStack Start virtual modules without Vite). Deploy via the generated config (npx wrangler deploy for staging, npx wrangler deploy --env production for production).

2. Staging Bindings & Secrets

Binding / ResourceStaging ValueNotes
ASSETSdist/ (run_worker_first: true)Worker controls routing order: moved articles -> trailing slash -> /prompts SSR -> public HTML -> static assets -> 404.
BUCKET (R2)slloy-staging-uploadsServed at /uploads/* with HTTP Range support (206).
HYPERDRIVEslloy-staging-neon (5c835a380e414013a32766e360976705)Connects directly to Neon slloy_staging (aws-ap-southeast-1, PostgreSQL 17, --caching-disabled).
IMAGE_QUEUEslloy-staging-images (DLQ: slloy-staging-images-dlq)Async image generation queue.
triggers.crons*/5 * * * *, 0 * * * *Matches server/src/scheduled.ts.

Staging Secrets (Top-Level Worker — Omit --env)

npx wrangler secret put ADMIN_JWT_SECRET -c wrangler.jsonc
npx wrangler secret put BETTER_AUTH_SECRET -c wrangler.jsonc
npx wrangler secret put STAGING_ACCESS_TEAM_DOMAIN -c wrangler.jsonc
npx wrangler secret put STAGING_ACCESS_AUD -c wrangler.jsonc
  • GitHub staging Environment Secrets: STAGING_NEON_DATABASE_URL (direct Neon connection string; migration asserts current_database() === 'slloy_staging'), STAGING_ACCESS_CLIENT_ID, STAGING_ACCESS_CLIENT_SECRET, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.
  • Stripe Sandbox on Staging: Keep PAYMENTS_ENABLED=false by default, or connect a dedicated staging Stripe test sandbox (sk_test_* / rk_test_*—live keys are rejected at startup when APP_ENV=staging). Never share the same Stripe test sandbox between staging and local stripe listen.

3. QA Testing Portal (https://staging.slloy.com/staging)

Mounted only when APP_ENV=staging (server/src/http/routes/staging.ts):

  • One-Click Test Account Creation: Creates a pre-verified test user (qa_<MMDD>_<rand>@staging.invalid) with 1,000 credits and issues an immediate login session (zero emails sent, no password required).
  • One-Click Credit Top-Up: Refills the current test user's credits (recorded in ledger as admin adjustment).
  • Browser Account Switcher: Switches between previously created @staging.invalid accounts (refuses to log into any real user domain).
  • One-Click /admin Login: When STAGING_ADMIN_USERNAME is configured, issues an admin session for that staging staff account and logs the caller's Cloudflare Access email.

4. Local Development Commands

npm ci
npm run db:up          # Starts/reuses shared local PostgreSQL 17 container (slloy-postgres-local)
npm run db:init        # Applies Drizzle migrations & seeds
npm run build:web      # Generates dist/ static assets for Worker
npm run dev:web        # Public site + /admin HMR on 127.0.0.1:5173 (auto-increments on port conflict)
npm run dev:api        # Workerd via Vite on 127.0.0.1:8787 (writes actual port to .docker-postgres/dev-api.json)

Or run npm run dev to launch database, Worker backend, and frontend dev servers together. To test local workerd against a remote Neon branch via Hyperdrive local connection override:

npm run build:web
CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE='postgresql://...@<neon-direct-host>/slloy_staging?sslmode=require' npm run dev:api

On this page