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
{
"platform": "cloudflare",
"agent": false,
"database": "d1"
}| Field | Values | Meaning |
|---|---|---|
platform | cloudflare, fly, railway, docker | The one platform this project deploys to. Decides the build target and which platform files exist |
agent | true, false | Whether the agent service is deployed beside the web app |
database | d1, postgres, sqlite | The 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.
| Flag | Meaning |
|---|---|
--agent / --no-agent | Include 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) |
--help | Print usage |
Flags that take a value accept --flag value or --flag=value. --agent and --no-agent take no value.
Exit codes:
| Code | When |
|---|---|
0 | The command completed |
1 | Any 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
platform | agent: false | agent: true |
|---|---|---|
cloudflare | d1, postgres | postgres |
fly | postgres, sqlite | postgres |
railway | postgres | postgres |
docker | postgres, sqlite | postgres |
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
platform | Files in the project root | Build target | deploy script |
|---|---|---|---|
cloudflare | wrangler.jsonc | cloudflare | wrangler deploy |
fly | fly.toml, and fly.agent.toml with the agent | node | fly deploy |
railway | .railway/railway.ts | node | railway up |
docker | compose.yaml | node | docker 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
cloudflare | fly | railway | docker | |
|---|---|---|---|---|
| Migrations | pnpm db:migrate:d1:remote for d1; pnpm db:migrate against the Postgres URL for postgres | release_command for postgres; at process start for sqlite | preDeploy of the web service | The migrate service |
| Migrator | Wrangler D1 migrations, or scripts/db/migrate.ts | scripts/db/migrate-runtime.mjs | scripts/db/migrate-runtime.mjs | scripts/db/migrate-runtime.mjs |
| Production administrator | pnpm db:bootstrap-super-admin --remote with DATABASE_DIALECT=d1; with DATABASE_URL for Postgres | fly ssh console --pty -C "node .output/scripts/bootstrap-super-admin.mjs" | railway ssh --service web, then the same script | docker compose exec web with the same script |
| Scheduled jobs | Cron Trigger, once a minute | Loop in the web process; min_machines_running = 1 | Loop in the web process | Loop in the web process |
| Secret store | wrangler secret put | fly secrets import | railway variables | --env-file .env.production |
| Agent service | Container bound as AGENT_SERVICE | App <name>-agent, fly.agent.toml | Service agent, one replica | Service agent |
| Web reaches the agent at | The container binding | http://<name>-agent.internal:3001 | http://agent.railway.internal:3001 | http://agent:3001 |
| Agent reaches the web at | AGENT_WEB_INTERNAL_URL, the Worker's public URL | http://<name>.internal:3000 | http://web.railway.internal:3000 | http://web:3000 |
| Postgres comes from | Your database, through the HYPERDRIVE binding | Your database, as the DATABASE_URL secret | The postgres resource in .railway/railway.ts | The postgres compose service |
| SQLite file | Not available | /data/app.db on the data volume | Not 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.
| Key | Generated when | Value |
|---|---|---|
BETTER_AUTH_SECRET | Always | 32 random bytes, hex |
CONFIG_ENCRYPTION_KEY | Always | 32 random bytes, hex; encrypts provider secrets in the admin config. Keep it stable |
SITE_URL | Always | The site URL given at creation; set it to the deployed origin |
POSTGRES_PASSWORD | docker with postgres | 32 random bytes, hex; the bundled Postgres password |
AGENT_INTERNAL_SIGNING_SECRET | agent is true | 32 random bytes, hex; shared by the web app and the agent service |
AGENT_RESOURCE_GRANT_SECRET | agent is true | 32 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
| Command | What it checks |
|---|---|
pnpm validate:deploy-targets | Every allowed combination renders the right files, refused ones are refused, the root files match the renderer, and the Node build starts |
pnpm smoke:node | The Node build, after pnpm build:node, on a throwaway SQLite database |
pnpm smoke:worker | The Worker build, after pnpm build, on a throwaway D1 database |