Environment setup -- local, staging, production

Quick start (local only, ~10 min)

pnpm install
pnpm run dev:setup          # copies .dev.vars + .env.local from examples (won't overwrite)
pnpm dev                    # worker :8787 + dashboard :3000

Open http://localhost:3000/onboarding → paste admin JWT (from Worker POST /auth/token with a project API key) → create room → message.

Worker: edit apps/worker/.dev.vars (from example). Minimum:

Dashboard: edit apps/dashboard/.env.local:

Leave Clerk keys empty for manual JWT onboarding.

Architecture (what talks to what)

Browser → Dashboard (Vercel) → Worker API (Cloudflare)
                ↓                    ↓
           Clerk (optional)      D1 + DO + KV + R2

Phase 1 -- Cloudflare Worker (staging or production)

1.1 Create resources (staging -- separate from prod)

Run from apps/worker:

# D1
pnpm exec wrangler d1 create fluxychat-staging
# → paste database_id into wrangler.staging.toml

# KV (rate limits)
pnpm exec wrangler kv namespace create RATE_LIMIT_KV
pnpm exec wrangler kv namespace create RATE_LIMIT_KV --preview
# → paste id + preview_id into wrangler.staging.toml

# R2
pnpm exec wrangler r2 bucket create fluxychat-attachments-staging

Production uses names in wrangler.toml (fluxychat, fluxychat-attachments) -- create if not already done.

1.2 Migrations

cd apps/worker
# Staging
pnpm exec wrangler d1 migrations apply fluxychat-staging --remote --config wrangler.staging.toml
# Production
pnpm exec wrangler d1 migrations apply fluxychat --remote

1.3 Worker vars (wrangler.toml / wrangler.staging.toml [vars])

1.4 Worker secrets (wrangler secret put NAME)

Required for hosted multi-tenant:

After bootstrap (see Phase 2):

Optional by feature:

Set hosted mode on Worker:

pnpm exec wrangler secret put HOSTED_MULTI_TENANT
# enter: true

pnpm exec wrangler secret put FLUXY_PLATFORM_PROJECT_ID
# enter: <uuid from provision bootstrap>

Or use [vars] for non-secret flags and secrets for keys.

1.5 Deploy

# Staging
pnpm exec wrangler deploy src/worker.js --config wrangler.staging.toml

# Production
pnpm --filter @fluxy-chat/worker deploy

1.6 Custom domain (API)

Cloudflare dashboard → Worker → Custom domains → add api.fluxychat.com (or staging subdomain).
wrangler.toml already has [[routes]] for production pattern.

Phase 2 -- Platform bootstrap (hosted tenants)

One-time per Worker deployment:

1. Set on Worker: ALLOW_PLATFORM_BOOTSTRAP=true, PLATFORM_BOOTSTRAP_SECRET=<random>.
2. From repo root:

PLATFORM_BOOTSTRAP_SECRET=<same> \
FLUXY_WORKER_URL=https://api.fluxychat.com \
pnpm provision:bootstrap

3. Read scripts/.provision-secrets.env (gitignored) -- contains FLUXY_CONSOLE_API_KEY and project UUID.
4. Copy to dashboard .env.local / Vercel:

FLUXY_CONSOLE_API_KEY=fc_...
FLUXY_CONSOLE_PROJECT_ID=<uuid>
FLUXY_PLATFORM_PROJECT_ID=<uuid>
NEXT_PUBLIC_FLUXYCHAT_CLOUD_URL=https://api.fluxychat.com

5. Copy to Worker secret: FLUXY_PLATFORM_PROJECT_ID=<uuid>, set HOSTED_MULTI_TENANT=true.
6. Disable bootstrap: remove ALLOW_PLATFORM_BOOTSTRAP or set false.

Phase 3 -- Dashboard (Vercel or self-host)

3.1 Environment variables

See apps/dashboard/.env.example, .env.staging.example, .env.production.example.

Do not expose FLUXY_CONSOLE_API_KEY to the browser -- only server routes use it.

3.2 Vercel project

1. Import repo → root apps/dashboard or monorepo with filter.
2. Build: pnpm --filter @fluxy-chat/dashboard build (or Turbo from root).
3. Env vars: paste from .env.production.example checklist.
4. Domains: app.fluxychat.com, optional status.fluxychat.com → same project (/status route exists).

3.3 Clerk (optional)

Clerk Dashboard → Application → API Keys → paste into Vercel.
Paths: Sign-in /sign-in, Sign-up /sign-up, after sign-up redirect /onboarding.

Phase 4 -- Stripe (optional, billing)

1. Stripe Dashboard → Developers → API keys → STRIPE_SECRET_KEY on Worker.
2. Webhook endpoint: https://api.fluxychat.com/webhooks/stripe → STRIPE_WEBHOOK_SECRET.
3. Without Stripe: /health shows paymentsEnabled: false; users stay on Free tier.

Phase 5 -- GitHub Actions (CI deploy)

Repository → Settings → Secrets and variables → Actions:

Create environments staging and production in GitHub → wire approval on production.

Manual deploy: Actions → Deploy → choose environment.

Phase 6 -- Smoke verification

# Worker
pnpm --filter @fluxy-chat/worker smoke:remote -- \
  --base-url https://api.fluxychat.com \
  --admin-jwt "<JWT>"

# Dashboard CI smoke (no worker)
cd apps/dashboard && CI=true pnpm test:e2e:smoke

# Full integrated (local worker + dashboard)
E2E_ADMIN_JWT=<jwt> pnpm --filter @fluxy-chat/dashboard test:e2e:integrated

Browser checks:

• https://<dashboard>/status — public health
• https://<dashboard>/onboarding — wizard
• https://<dashboard>/billing — load plan

Configuration matrix (minimum vs full)

Troubleshooting

See also RUNBOOK_DEPLOY_ROLLBACK.md, open-beta-deploy-guide.