Deployment

Deployment boundaries

Flare runs natively on Workers. It does not use OpenNext or a Next.js deployment command. apps/web/wrangler.jsonc is local configuration; the muse CLI generates remote target configuration. Do not publish the local config directly to production.

Public demo: flare.musemvp.com. It is MuseMVP's instance, not your deployment target. New products need their own names; upgrades must preserve existing identity.

1. Prepare the account

Use Node 22.12+ and pnpm 10.26.2. The token needs relevant Worker, D1, R2, and Queues edit permissions, plus zone permissions for a custom domain. Prepare Email Sending and a verified sender domain, and check AI/Queues availability in your account.

Copy the root example:

cp .env.example .env

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-deployment-token
APP_URL=https://app.your-domain.com
AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
MAIL_FROM=Your Product <[email protected]>
ADMIN_EMAIL=[email protected]

APP_URL is an HTTPS origin without a path. When absent, the CLI can derive workers.dev. Preserve existing production AUTH_SECRET. ADMIN_EMAIL promotes a matching registered/verified account rather than seeding one. Keep the deployment token out of app .dev.vars and frontend code.

2. Review five resource identities

Edit production in packages/cli/src/target-resources.ts:

Names start with a lowercase letter, contain lowercase letters/digits/hyphens, and are 2–63 characters. Use distinct configured names. Changing product.slug does not override explicit production names.

New products create independent resources. Existing deployments must preserve account, database, and bucket identities; renaming can create empty resources without migrating history. Preview and production are separate targets, not shared test data.

3. Diagnose and plan without creating resources

pnpm muse:doctor --target production --json
pnpm muse:deploy --target production --plan --json

Doctor checks inputs and capabilities. Plan reads remote inventories and pending migrations without provisioning. Review the account, origin, actions, migrations, risks, and blockers. Unexpected create actions during upgrades warrant investigation.

The CLI does not generate migrations or rotate existing secrets. Generate/review SQL in development. High-risk pending forms such as DROP, TRUNCATE, DELETE, and UPDATE SET block automated deployment and require a separately reviewed backup/application process.

4. Deploy

pnpm muse:deploy --target production --yes --json

The CLI runs build, type checks, unit tests, lint diagnostics, and Workers tests before provisioning. It creates/adopts resources, builds target configuration, removes copied local .dev.vars, applies remote migrations, uploads secrets, and publishes.

State lives in .muse/<target>.deployment.json, with generated config at apps/web/.muse/<target>.wrangler.json. Both are ignored. Existing state checks account consistency; do not edit it to bypass an account mismatch.

Inspect the failure stage. A pre-provisioning check failure does not imply resources were created, while post-publication smoke failure does not imply publication never occurred.

5. Verify smoke and manual gates

pnpm muse:verify --target production --json

Public checks cover /api/health, /, /zh, /auth/login, and /pricing. Confirm HTTP status and production environment. A new custom domain may need DNS propagation before verify succeeds.

Exit codes are 0 for command/smoke success, 1 for operational failure, 2 for blocked, and 3 for smoke failure. Use pnpm --silent when consuming JSON-only stdout.

smokePassed does not equal manual verified. Separately accept registration/code delivery, recovery, OAuth/Turnstile; R2 and cross-user isolation; key revocation; real AI, queues, credit settlement/compensation; and each enabled gateway's test purchase, signed event, cancellation, and refund.

Keep billing disabled when unused instead of supplying fake products to satisfy checks.

CI and Workers Builds

Remote builds do not read your local .env. Configure the same encrypted environment variables, Node 22, and the locked pnpm version. Build, then deploy with the muse CLI; retain its validation and resource management instead of switching to raw wrangler deploy.

Process variables override root .env, which overrides target secrets JSON defaults. Inspect CI precedence when an edit appears ineffective.

New machines, upgrades, and rollback

Preserve secrets, exact names, account, and deployment records. Git does not restore ignored files. The CLI can rediscover existing resources by exact names, but review the plan first. Do not commit secrets to simplify collaboration.

Worker rollback does not revert D1 data or migrations. Keep schemas backward-compatible and prepare a separate recovery plan for risky data changes. The source deployment runbook provides a recording example; each release still needs its own commit and results.

Use troubleshooting for blockers instead of deleting checks or resources.