Kernlift

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 build finishes 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

PlatformDatabasesAgent servicePick it when
CloudflareD1, or Postgres through HyperdriveCloudflare container, Postgres onlyYou want a Worker with D1, R2 and KV bindings
Fly.ioSQLite on a volume, or PostgresA second app on the private network, Postgres onlyYou want a container close to your users and bring your own Postgres
RailwayPostgresA second serviceYou want the platform to create Postgres with the app
DockerSQLite on a volume, or the bundled PostgresA compose service, Postgres onlyYou 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.json

Run 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-typegen

The 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_KEY

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

On 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 --remote

Verify

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