Deploy to Cloudflare

Cloudflare is the maintained production deployment target. Self-hosting means operating this topology in your own Cloudflare account with your own database, keys and OAuth applications. The API Hono application runs directly in a Cloudflare Worker; the Container binding remains available for explicitly planned emergency recovery. Domain packages do not depend on a particular hosting platform.

What you deploy

Postgres stores platform state; hosted production uses Neon. Hyperdrive supplies Worker database connections. R2 stores blobs through the S3-compatible adapter. The Server's Dockerfile builds the retained emergency-recovery image, not a separate Compose production service.

1. Configure your account

Install Node.js 22+, pnpm, Docker and the repository dependencies. Authenticate Wrangler and confirm the intended account:

pnpm install
pnpm --filter server exec wrangler login
pnpm --filter server exec wrangler whoami

Review every app's wrangler.jsonc. Replace the repository's production account ID and domains with yours. Create the referenced Queues and dead-letter queues, Hyperdrive configurations and R2 bucket, and replace their names/IDs and any cross-Worker binding names. Configure the referenced logging and tracing destinations, or remove those destination references for your own observability setup. The repository is not a one-command infrastructure provisioner.

The hosted topology binds the marketing Worker to the Docs Worker. The marketing Worker owns the apex Custom Domain and forwards /docs, /zh/docs, and /sitemap-docs.xml. A self-hosted deployment can keep this layout or change both Wrangler configurations and the public URL settings together.

Onboard your sending domain under Cloudflare Email Service before deploying the native API Worker. Set EMAIL_FROM to an address on that domain and update the EMAIL binding's allowed_sender_addresses in apps/server/wrangler.jsonc. Cloudflare accepts the message synchronously and reports final delivery separately; configure Email Sending event subscriptions if you need delivered/bounced/failed state in your own observability pipeline.

Keep API origins, CORS, OAuth callback URLs and frontend .env.production values consistent. VITE_* values are public and compiled into site assets. Set VITE_MANAGED_OAUTH_PROVIDERS only for providers actually configured on your API.

2. Supply runtime secrets

Each app declares required secrets under secrets.required in its Wrangler file. Use the validated environment schemas as the complete configuration contract. For example, these commands prompt for values without embedding them in source:

pnpm --filter server exec wrangler secret put DATABASE_URL --env production
pnpm --filter server exec wrangler secret put BETTER_AUTH_SECRET --env production
pnpm --filter server exec wrangler secret put CONNECTOR_ENCRYPTION_KEY --env production
pnpm --filter server exec wrangler secret put SERVER_DEPLOYMENT_CONTROL_TOKEN --env production

Also configure the remaining required OTLP, Queue and R2 credentials, plus the provider OAuth and billing secrets needed by your deployment. Secrets are scoped to each Worker; setting a Server secret does not configure the Trigger or billing Worker. Use the same random, 32-character-or-longer deployment control token in the Server Worker and the GitHub production environment.

RESEND_API_KEY is optional for the native Worker, but the retained Container recovery path uses the Resend adapter because native Worker bindings cannot be passed into the Container process. Keep it configured if recovery-mode email delivery is required.

Back up the encryption key securely. Replacing CONNECTOR_ENCRYPTION_KEY without re-encrypting stored credentials makes existing connections unreadable.

3. Prepare the database and catalog

With the production database URL supplied through a protected environment:

pnpm db:migrate
pnpm tools:publish-catalog

The commands target DATABASE_URL. Local .env values must not accidentally select a development database. Server startup does not publish the Runtime Catalog. If you use billing, run pnpm --filter worker provision with the target database and Stripe credentials when provisioning or changing plans; it is an operational command, not a second scheduled runtime.

4. Validate and publish

From a clean checkout:

pnpm deploy:cloudflare:dry-run
pnpm deploy:cloudflare

The root command deploys all six apps with strict configuration checks. The Server task uploads a zero-traffic candidate, runs configuration reconciliation and pending application migrations, evaluates read-only readiness, and promotes only the exact source SHA. It restores the previous version's traffic if the exact-release smoke check fails. A normal local deploy does not migrate the database schema automatically; run schema migrations first.

The Release GitHub workflow deploys the exact released commit through Deploy (Cloudflare). Configure these secrets in the GitHub production environment:

Runtime secrets remain in Cloudflare. CI loads public build configuration from the app-scoped .env.production files and does not read AWS configuration stores. If the Server Worker lacks the control-secret binding, the workflow installs it from the protected GitHub value after migration and before upload; it does not overwrite an existing binding.

5. Verify and recover

Check the API root for 200 OK and the expected x-open-connector-release header. Run the marketing/docs smoke commands and verify the console, one authenticated Tool call, provider ingress and Queue/Cron processing. Inspect logs, traces and metrics in the configured observability backend.

The Server coordinator retains the previous immutable Worker version at zero percent after promotion. A failed exact-release smoke check restores it automatically; operators can restore that version manually for later failures. Check database compatibility before rolling back code; deployment does not undo migrations or external provider effects.

The maintained workflow does not include AWS/OpenTofu provisioning or a second production scheduler. Existing infrastructure from an older installation needs a separate inventory before decommissioning.