Deploy your project
Pick one of the four platforms, store the generated secrets, migrate, deploy, and create the production administrator.
This tutorial takes the project you ran locally to a public URL. A project deploys to one platform:
Cloudflare, Fly.io, Railway or a Docker host. The choice is recorded in deploy.config.json, and only
that platform's files are in the repository. This page is the shortest path. Each platform has a full
guide.
Before you begin
- A project that builds locally:
pnpm buildfinishes without errors. - The CLI of the platform you deploy to, signed in:
wrangler,fly,railway, or Docker Compose. - For Postgres on Cloudflare or Fly.io: a Postgres database and its connection URL. Railway and Docker create their own.
Choose a platform
| Platform | Databases | Agent service | Pick it when |
|---|---|---|---|
| Cloudflare | D1, or Postgres through Hyperdrive | Cloudflare container, Postgres only | You want a Worker with D1, R2 and KV bindings |
| Fly.io | SQLite on a volume, or Postgres | A second app on the private network, Postgres only | You want a container close to your users and bring your own Postgres |
| Railway | Postgres | A second service | You want the platform to create Postgres with the app |
| Docker | SQLite on a volume, or the bundled Postgres | A compose service, Postgres only | You run your own server |
Cloudflare gets the Worker build; the other three get the Node build that the root Dockerfile
packages. The agent service is optional everywhere and always needs Postgres. The model behind this
table is in Deployment model.
Deploy
Confirm or switch the platform
The repository records its platform in deploy.config.json. Read it:
cat deploy.config.jsonRun deploy-target for the platform you want, even when it is the one already recorded: a fresh
clone has no .env.production, and this command generates it. The command writes the platform's
files, moves another platform's files to .kernlift/previous-deploy/, completes .env.production
and prints the remaining steps. It creates nothing remote and moves no data.
pnpm kernlift deploy-target fly --no-agent
pnpm cf-typegenThe options are listed in the deployment configuration reference.
Check the production values
.env.production holds the generated session secret and the public URL. It is ignored by git and
is never committed. Set SITE_URL in it to the address the site will be served from. The commands below read secrets from this file over standard input, so no value appears on a
command line.
Migrate and deploy on your platform
pnpm db:migrate:d1:remote
pnpm build
pnpm run deploy
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_KEYwrangler.jsonc must carry real ids for D1, R2 and KV first. Full guide:
Deploy to Cloudflare Workers.
Use pnpm run deploy
pnpm deploy without run is pnpm's own workspace command, not the project script.
Create the production administrator
The production database is not your local one, so it needs its own administrator. On Fly.io, Railway and Docker the image carries a script that prompts for the email and password:
fly ssh console --app my-saas --pty -C "node .output/scripts/bootstrap-super-admin.mjs"
docker compose --env-file .env.production exec web node .output/scripts/bootstrap-super-admin.mjsOn Railway, open a shell with railway ssh --service web and run
node .output/scripts/bootstrap-super-admin.mjs. On Cloudflare D1, run it from the checkout with
wrangler signed in:
DATABASE_DIALECT=d1 SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin --remoteVerify
Open /setup on the deployed URL and sign in as the administrator. Then open /admin/config/auth and
check the Base URL; change it there if the site answers on another domain.
- The first line names the platform, the database and whether the agent service is included.
- Session secret is ready.
- Scheduled jobs turns ready within a couple of minutes of the first deploy.
The checklist reads the live database, so configure the providers you need from there, starting with
Email delivery. Storage is configured in /admin/config/storage; on Cloudflare you can also use
the bucket binding the runtime detects.
Troubleshooting
The app refuses to start with a session secret error
BETTER_AUTH_SECRET did not reach the platform while APP_ENV is not development. Store it again
with the command for your platform.
OAuth sign-in or email links point at the wrong address
OAuth callbacks and links in emails use the Base URL at /admin/config/auth. Correct it there; the
change takes effect within about 30 seconds, without a redeploy.
Scheduled jobs stay not ready on /setup
Nothing is starting the rounds. The item names the switch for your platform: the Cron Trigger in
wrangler.jsonc on Cloudflare, a running web process on the others.
Next steps
Deploy to Cloudflare Workers
D1, Hyperdrive for Postgres, and the agent container.
Deploy to Fly.io
SQLite on a volume or Postgres, with the agent as a second app.
Deploy to Railway
Services and Postgres from .railway/railway.ts.
Deploy with Docker Compose
One server, compose.yaml and a reverse proxy.
deploy.config.json
Allowed combinations and what each platform owns.
Add an admin or workspace page
Add one screen under /admin or /app with a guarded server function, copy in both locales and a navigation entry.
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.