Deploy to Cloudflare Workers
Deploy the Worker on D1 or on Postgres through Hyperdrive, store the session secret, create the production administrator, and optionally add the agent container.
On Cloudflare the project is a Worker with an R2 bucket and a KV namespace. Its database is D1, or Postgres reached through Hyperdrive. The agent service is optional and runs as a Cloudflare container, on Postgres only. Use this guide for the first production deployment, or after you change a binding.
Before you begin
- A Cloudflare account, with
wranglersigned in (npx wrangler login). deploy.config.jsonsays"platform": "cloudflare". If it names another platform, runpnpm kernlift deploy-target cloudflarefirst; see deploy.config.json.- For Postgres: an empty Postgres database and its connection URL; see Use Postgres and Supabase.
.env.productionin the project root.pnpm kernlift deploy-target cloudflaregenerates it with the session secret.
Create resources in Cloudflare
Sign in to Wrangler with the account where you will deploy. Replace my-saas with your project name.
Choose the database connection
For D1, create the database and record the printed database_id.
npx wrangler d1 create my-saas-edgeFor Postgres, create Hyperdrive instead. Replace the example connection string with yours and keep the configuration ID.
npx wrangler hyperdrive create my-saas-db --connection-string='postgresql://USER:PASSWORD@HOST:5432/DB'Create the object bucket
Keep the bucket name for the R2 binding.
npx wrangler r2 bucket create my-saas-assetsCreate the cache namespace
Keep the namespace ID for the KV binding.
npx wrangler kv namespace create my-saas-cacheCopy the D1 database_id, the KV id, the R2 bucket name and the Hyperdrive id into the existing wrangler.jsonc entries. If Wrangler offers to add a binding automatically, decline. The template already declares EDGE_DB, BUCKET, CACHE and HYPERDRIVE, and the application looks bindings up by those names. See creating D1, creating R2 buckets, creating KV namespaces and Hyperdrive.
Bind the resources
Fill in wrangler.jsonc
Replace every replace-with-... placeholder with a real id and keep the worker name. A D1 project carries:
"r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-saas-assets" }],
"kv_namespaces": [{ "binding": "CACHE", "id": "<your KV namespace id>" }],
"d1_databases": [
{
"binding": "EDGE_DB",
"database_name": "my-saas-edge",
"database_id": "<your D1 database id>",
"migrations_dir": "./drizzle/migrations/sqlite"
}
]A Postgres project has no d1_databases block. It sets DATABASE_DIALECT to postgres and DATABASE_ADAPTER to hyperdrive under vars, and carries:
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<your Hyperdrive id>" }]Set the production variables
Under vars, a D1 project ships APP_ENV as development; change it to production. Add SITE_URL with your public origin. Secrets never go in this file.
Regenerate the binding types
pnpm cf-typegenRe-rendering sets your wrangler.jsonc aside
pnpm kernlift deploy-target cloudflare --dialect postgres turns a D1 project into a Hyperdrive one by rendering wrangler.jsonc again from the template. Your current file, with its resource ids, moves to .kernlift/previous-deploy/wrangler.jsonc; copy the bucket name and KV id from it into the new file.
Migrate and deploy
Apply the migrations
For D1:
pnpm db:migrate:d1:remoteFor Postgres, migrate the database directly from the checkout. Hyperdrive is a Worker binding, so the migration uses the Postgres URL itself:
DATABASE_DIALECT=postgres DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB' pnpm db:migrateBuild and deploy
pnpm build
pnpm run deployThe script runs wrangler deploy and prints the Worker URL.
Store the session secret
A secret is attached to an existing Worker, so store it after the first deploy. The value is read from .env.production over standard input:
grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put BETTER_AUTH_SECRET
grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2- | npx wrangler secret put CONFIG_ENCRYPTION_KEYCreate the production administrator
For D1, run the bootstrap from the checkout; --remote reaches the deployed database through wrangler:
DATABASE_DIALECT=d1 SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin --remoteFor Postgres, point it at the production database:
DATABASE_DIALECT=postgres DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DB' SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-adminThe script reads the email and password from the environment. It does not accept them as arguments.
Use pnpm run deploy
pnpm deploy without run is pnpm's own workspace command, not the project script.
Add the agent container
Skip this section if the project does not include the agent. The agent needs Postgres, so the project must be on Hyperdrive. pnpm kernlift deploy-target cloudflare --agent renders wrangler.jsonc with the containers and durable_objects blocks and adds the agent secrets to .env.production.
Store the agent secrets
grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put AGENT_INTERNAL_SIGNING_SECRET
grep '^AGENT_RESOURCE_GRANT_SECRET=' .env.production | cut -d= -f2- | npx wrangler secret put AGENT_RESOURCE_GRANT_SECRETStore AGENT_DATABASE_URL the same way. It is the direct Postgres URL. The container cannot use the Hyperdrive binding, so it connects to the same database directly.
Point the agent back at the Worker
Set AGENT_WEB_INTERNAL_URL under vars in wrangler.jsonc to the Worker's public URL. The agent service calls the web app there.
Deploy again
pnpm build
pnpm run deployWrangler builds the container image from apps/agent-service/Dockerfile. One instance runs, because the service holds run state in memory.
Verify
pnpm run deployprints the Worker URL, and the site loads there./setup, signed in as the administrator, names Cloudflare and the database in its first line and shows Session secret as ready./admin/config/authshows the Base URL the site answers on. Change it there if the site uses another domain.- Scheduled jobs turns ready within a couple of minutes. The Cron Trigger in
wrangler.jsoncruns a round every minute. - With the agent,
/app/agentopens the workbench. - In the repository,
pnpm smoke:workerafterpnpm buildruns the built Worker on a throwaway D1 database, andpnpm validate:deploy-targetschecks the rendered configuration.
Troubleshooting
EDGE_DB D1 binding is required when DATABASE_ADAPTER=d1
The Worker has no D1 binding named EDGE_DB. Check d1_databases in wrangler.jsonc and deploy again.
DATABASE_ADAPTER=hyperdrive needs the HYPERDRIVE Worker binding.
The hyperdrive entry in wrangler.jsonc is missing or still carries the placeholder id. Put the real Hyperdrive id there and deploy again.
The Worker refuses to start with a session secret error
APP_ENV is not development and BETTER_AUTH_SECRET is missing. Store it with the command above.
Pages fail with missing tables
Migrations ran against a local database only. Run pnpm db:migrate:d1:remote, or pnpm db:migrate against the Postgres URL.
Scheduled jobs stay not ready
Check that wrangler.jsonc keeps "triggers": { "crons": ["* * * * *"] } and that the deployed Worker lists the trigger.
Reference
- deploy.config.json and Environment variables
- Cache and Storage
- Wrangler configuration
- D1, R2, KV, Hyperdrive, Containers
Next steps
Deploy your project
Pick one of the four platforms, store the generated secrets, migrate, deploy, and create the production administrator.
Deploy to Fly.io
Create the Fly app, import the generated secrets, deploy the Node image with migrations, create the production administrator, and optionally add the agent app.