Kernlift

Deployment configuration

deploy.config.json and the kernlift deploy-target command that rewrites it: the combinations it allows, the files each platform owns, the keys of .env.production, and how each platform migrates and bootstraps.

deploy.config.json is the committed record of where a project deploys. The repository you clone carries it, kernlift deploy-target rewrites it, vite.config.ts reads it to pick the build target, and the app bundles it so /setup can report it. It holds no secrets. For the reasoning, see Deployment model.

Fields

deploy.config.json
{
  "platform": "cloudflare",
  "agent": false,
  "database": "d1"
}
FieldValuesMeaning
platformcloudflare, fly, railway, dockerThe one platform this project deploys to. Decides the build target and which platform files exist
agenttrue, falseWhether the agent service is deployed beside the web app
databased1, postgres, sqliteThe production database. Local development uses a SQLite file whatever this says

A project without the file builds for Cloudflare. Do not edit the file by hand. The platform files are rendered together with it, so change it with kernlift deploy-target. Its flags are below.

Switch platforms with kernlift deploy-target

kernlift deploy-target <cloudflare|fly|railway|docker> [flags] runs in a project directory, one that has deploy.config.json. It rewrites the file and the platform files, points the deploy script at the platform's deploy command, moves the other platforms' files to .kernlift/previous-deploy/, adds missing keys to .env.production and prints the next steps. It creates no remote resource and moves no data. It is the only kernlift command a cloned project needs; everything else is a script.

The CLI has no dependencies and runs on Node 20 or later. Its source is in tools/kernlift/ of your clone. Run it with pnpm kernlift deploy-target <platform>. The kernlift script in the root package.json runs tools/kernlift/src/kernlift.js, so nothing is fetched from npm.

FlagMeaning
--agent / --no-agentInclude or drop the agent service (default: the project's current choice)
--dialect <db>Production database (default: the current one if the new platform allows it, otherwise the platform's first choice)
--region <code>Fly.io primary region (default iad)
--cwd <dir>Project directory (default: the current directory)
--helpPrint usage

Flags that take a value accept --flag value or --flag=value. --agent and --no-agent take no value.

Exit codes:

CodeWhen
0The command completed
1Any error (the message is printed on stderr): an unknown platform, a combination the platform does not allow, or a directory without deploy.config.json

Allowed combinations

platformagent: falseagent: true
cloudflared1, postgrespostgres
flypostgres, sqlitepostgres
railwaypostgrespostgres
dockerpostgres, sqlitepostgres

That is eleven combinations. The CLI rejects any other combination before it writes a file. The agent needs Postgres because its runs need transactions and a database shared by two processes. sqlite is a single-machine option, and d1 exists only on Cloudflare. When kernlift deploy-target is run without --dialect, it keeps the current database if the new platform allows it and otherwise takes the first value in the row.

What each platform owns

platformFiles in the project rootBuild targetdeploy script
cloudflarewrangler.jsonccloudflarewrangler deploy
flyfly.toml, and fly.agent.toml with the agentnodefly deploy
railway.railway/railway.tsnoderailway up
dockercompose.yamlnodedocker compose --env-file .env.production up -d --build

The node build target is packaged by the root Dockerfile. The agent service uses apps/agent-service/Dockerfile on every platform. Both Dockerfiles stay in the repository whatever the platform.

The platform files are rendered from templates that ship with the CLI. When kernlift deploy-target renders the platform the project already uses, a file whose content differs from the new render (resource ids filled into wrangler.jsonc, hand edits) is moved to .kernlift/previous-deploy/ before the new one is written. A file that is identical is left alone.

Per-platform behaviour

cloudflareflyrailwaydocker
Migrationspnpm db:migrate:d1:remote for d1; pnpm db:migrate against the Postgres URL for postgresrelease_command for postgres; at process start for sqlitepreDeploy of the web serviceThe migrate service
MigratorWrangler D1 migrations, or scripts/db/migrate.tsscripts/db/migrate-runtime.mjsscripts/db/migrate-runtime.mjsscripts/db/migrate-runtime.mjs
Production administratorpnpm db:bootstrap-super-admin --remote with DATABASE_DIALECT=d1; with DATABASE_URL for Postgresfly ssh console --pty -C "node .output/scripts/bootstrap-super-admin.mjs"railway ssh --service web, then the same scriptdocker compose exec web with the same script
Scheduled jobsCron Trigger, once a minuteLoop in the web process; min_machines_running = 1Loop in the web processLoop in the web process
Secret storewrangler secret putfly secrets importrailway variables--env-file .env.production
Agent serviceContainer bound as AGENT_SERVICEApp <name>-agent, fly.agent.tomlService agent, one replicaService agent
Web reaches the agent atThe container bindinghttp://<name>-agent.internal:3001http://agent.railway.internal:3001http://agent:3001
Agent reaches the web atAGENT_WEB_INTERNAL_URL, the Worker's public URLhttp://<name>.internal:3000http://web.railway.internal:3000http://web:3000
Postgres comes fromYour database, through the HYPERDRIVE bindingYour database, as the DATABASE_URL secretThe postgres resource in .railway/railway.tsThe postgres compose service
SQLite fileNot available/data/app.db on the data volumeNot available/data/app.db on the data volume

.env.production

Generated in the project root and completed by kernlift deploy-target. The file is written with mode 0600 and is ignored by git and by the Docker build context. An existing file is kept. A later run adds missing keys and never changes or removes a value.

KeyGenerated whenValue
BETTER_AUTH_SECRETAlways32 random bytes, hex
CONFIG_ENCRYPTION_KEYAlways32 random bytes, hex; encrypts provider secrets in the admin config. Keep it stable
SITE_URLAlwaysThe site URL given at creation; set it to the deployed origin
POSTGRES_PASSWORDdocker with postgres32 random bytes, hex; the bundled Postgres password
AGENT_INTERNAL_SIGNING_SECRETagent is true32 random bytes, hex; shared by the web app and the agent service
AGENT_RESOURCE_GRANT_SECRETagent is true32 random bytes, hex

You add DATABASE_URL yourself for Postgres on fly, and the Fly secret import then includes it. On cloudflare the agent container's direct Postgres URL is stored as the AGENT_DATABASE_URL secret. Values reach the platform over standard input and are never printed. The file is separate from .env, which holds the development values for your machine.

.kernlift/previous-deploy/

When kernlift deploy-target switches platforms, the files of the other platforms that are in the project root move here, keeping their relative path, for example .kernlift/previous-deploy/wrangler.jsonc. Nothing is deleted. A copy already there is never overwritten. A later one takes the next free name, wrangler.jsonc.1, then .2.

Use the directory to recover earlier content, such as the resource ids in an earlier wrangler.jsonc. Switching back to a platform renders its files from the template again and does not restore the copy.

Checks

CommandWhat it checks
pnpm validate:deploy-targetsEvery allowed combination renders the right files, refused ones are refused, the root files match the renderer, and the Node build starts
pnpm smoke:nodeThe Node build, after pnpm build:node, on a throwaway SQLite database
pnpm smoke:workerThe Worker build, after pnpm build, on a throwaway D1 database

Next steps