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. 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.

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.

Create the Server Hyperdrive configuration with SQL response caching disabled, or disable caching on an existing configuration before serving traffic:

pnpm --filter server exec wrangler hyperdrive create <name> \
  --connection-string <database-url> \
  --caching-disabled

pnpm --filter server exec wrangler hyperdrive update <hyperdrive-id> \
  --caching-disabled

Server authorization state and Trigger Event Stream cursors require read-after-write consistency. A cache-enabled binding can return stale state after a committed write.

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. Publish the catalog and deploy the Server's public catalog API before building Web and Docs. Both sites use the SDK for catalog metadata and build-time page enumeration; managed OAuth availability comes from the Server.

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. For automatic Server deployment, use the same random, 32-character-or-longer deployment control token in the Server Worker and its Cloudflare Workers Builds environment.

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 Server declares its Durable Object through exports and deploys directly with wrangler deploy. See the repository runbook for the required database and catalog preparation.

The root command deploys all six apps with strict configuration checks. The Server task checks bindings, deploys the new version, runs application preparation and readiness checks, and verifies the public release SHA. A normal local deploy does not migrate the database schema automatically; run schema migrations first.

To deploy the Server automatically from main, connect apps/server to Cloudflare Workers Builds, leave the build command empty, and use pnpm -w run db:migrate && pnpm -F @open-connector/server deploy:cloudflare as the deploy command. Configure the production database's direct DATABASE_URL and the deployment control token as Builds secrets. Runtime Worker secrets are not available in Builds. A failed schema migration stops deployment. This Build does not deploy the other five Workers or publish the Runtime Catalog. The GitHub Release workflow creates tags and publishes SDK and CLI artifacts; it does not deploy Cloudflare Workers.

For branch previews, enable Worker Previews in the connected Worker's Builds settings. Set the Previews Base command to pnpm -F @open-connector/server deploy:cloudflare:preview and supply the account's PREVIEW_WORKERS_DEV_SUBDOMAIN as a Build variable. Use a separate schema-only database and Preview-specific secrets and Queue bindings. Server previews do not run database migrations or background consumers; see the repository runbook for the isolation checklist.

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.

Cloudflare retains previous immutable Worker versions for manual rollback. A failed post-deploy check can leave the new Server version serving traffic; restore the previous version manually if needed. Check database compatibility before rolling back code; deployment does not undo migrations or external provider effects.

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