Deployment model
One platform per project, two build targets, which databases and agent setups each platform allows, where secrets live, when migrations run, and how scheduled jobs are started.
A project deploys to one platform: Cloudflare, Fly.io, Railway or a Docker host. The choice is stored in a
committed file, deploy.config.json. It determines which build runs, which
platform files are in the repository, which databases are possible, and how migrations and scheduled
jobs are started. Routes, guards, repositories and validators are the same on every platform. For the
steps, see Deploy your project.
One platform per project
{
"platform": "cloudflare",
"agent": false,
"database": "d1"
}The file is committed in the repository you clone, and
kernlift deploy-target <platform> rewrites it. It holds no secrets. The build reads it to pick
a target, and the app bundles it, so /setup on a deployment reports the platform, database and agent
choice that build was made for.
Only the chosen platform's files are in the project root: wrangler.jsonc, or fly.toml and
fly.agent.toml, or .railway/railway.ts, or compose.yaml. The deploy script in package.json
runs that platform's deploy command. Every field and file is listed in
deploy.config.json.
Two build targets
| Target | Platforms | Server entry | Output | Started by |
|---|---|---|---|---|
cloudflare | Cloudflare | src/server-entry.ts | dist/ | wrangler deploy |
node | Fly.io, Railway, Docker | src/server-entry.node.ts | .output/ | node .output/server/index.mjs |
pnpm build picks the target from deploy.config.json, so a build gives the same output wherever it
runs, including a platform's remote builder. pnpm build:cloudflare and pnpm build:node name the
target explicitly. A project without the file builds for Cloudflare.
The Worker entry also carries the Cron Trigger handler and the agent container class. The Node entry
has neither. It starts the scheduled-jobs loop when the process loads. The root Dockerfile packages
the Node build for all three Node platforms. See Run the Node build.
Platform, database and agent matrix
| Cloudflare | Fly.io | Railway | Docker | |
|---|---|---|---|---|
| Database without the agent | D1 or Postgres through Hyperdrive | Postgres or SQLite on a volume | Postgres | Postgres or SQLite on a volume |
| Database with the agent | Postgres through Hyperdrive | Postgres | Postgres | Postgres |
| Agent service | Cloudflare container | The <name>-agent app | The agent service | The agent compose service |
| Object storage | R2 binding or S3-compatible | S3-compatible | S3-compatible | S3-compatible |
| Cache | KV or process memory | Process memory | Process memory | Process memory |
The agent needs a database with transactions that the web app and the agent service share, so it
always runs on Postgres. SQLite is a single-machine option: one machine owns the file. D1 exists only
on Cloudflare. kernlift deploy-target rejects a combination outside this table
before it writes anything.
The agent service is one instance, because it holds run state in memory, and it is reached only on the platform's private network. A deployment without it is a complete web app. See Agent runtime.
Secrets
Production secrets are generated once into .env.production: the session secret, the agent signing
secrets when the agent is included, and the password of the bundled Postgres on Docker. The file is
written with mode 0600 and is ignored by git and by the Docker build context. A second run of the CLI
fills in missing keys and never rotates a value that is already there.
From that file the values go to the platform's secret store: wrangler secret put,
fly secrets import, railway variables, or docker compose --env-file .env.production. The
commands read them over standard input, so a secret is never printed, placed on a command line or
written into a committed file. Provider credentials are not part of this. They stay in
the database and are managed in /admin/config/*.
Migrations before traffic
The schema is built only by the migration chain, and each platform applies it before the new version serves requests.
| Platform | What applies the migrations |
|---|---|
| Cloudflare with D1 | pnpm db:migrate:d1:remote, run before pnpm run deploy |
| Cloudflare with Postgres | pnpm db:migrate from the checkout, against the Postgres URL |
| Fly.io with Postgres | release_command in fly.toml, on a temporary machine |
| Fly.io with SQLite | The app process, before the server starts; a release machine has no volume |
| Railway | The preDeploy step of the web service |
| Docker | The migrate compose service; web starts after it succeeds |
The Node platforms run node scripts/db/migrate-runtime.mjs, which needs no TypeScript runner and
keeps the same bookkeeping table as pnpm db:migrate, so the two can be used on the same database.
The production administrator is a separate step, because the production database is not the local
one. The Node image carries node .output/scripts/bootstrap-super-admin.mjs. Cloudflare runs
pnpm db:bootstrap-super-admin from the checkout, with --remote for D1.
Scheduled jobs
Background work runs once a minute through runScheduledJobs(): fulfilment retries, credit expiry
and unfinished AI tasks. What starts a round depends on the build target.
- Cloudflare: the per-minute Cron Trigger in
wrangler.jsonccalls the Worker'sscheduledhandler. - Fly.io, Railway, Docker: a loop inside the web process. Every replica runs the loop, and a lock row in the config table lets one of them run each round. No separate jobs process or platform cron is configured.
A stopped web process runs nothing, which is why fly.toml keeps min_machines_running = 1. Setting
JOBS_IN_PROCESS=false turns the loop off. An external cron then has to call pnpm jobs:run.
Each round records when it ran. /setup shows Scheduled jobs as not ready when no round has run
for five minutes or the last one had failures, and names the switch for the deployed platform.
What switching does
kernlift deploy-target <platform> re-renders the deployment from the templates that ship with the
CLI. It rewrites deploy.config.json, writes the new platform's files, points the deploy script at
the new platform, and adds any missing keys to .env.production. Files of the previous platform move
to .kernlift/previous-deploy/. Nothing is deleted, and a copy already there is never overwritten.
Switching changes files only. It creates no remote resource, does not touch the running deployment and
moves no data. The next pnpm build follows the new target. Flags are in the
deployment configuration reference.
Local development
Local development is the same for every platform: pnpm dev on a SQLite file. A project whose
production database is Postgres still develops on SQLite locally.
DATABASE_DIALECT=sqlite
DATABASE_URL=./local.dbpnpm db:migrate
SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin
pnpm devThe bootstrap step creates the first administrator, the permission set and the super admin role, and writes the baseline operational content. There is no demo data, and external provider success is never faked.
Database adapters
There are two schema families, SQLite and Postgres, and every repository is written against both.
DATABASE_DIALECT picks the family. DATABASE_ADAPTER picks how to connect and defaults to the
dialect.
| Adapter | Dialect | Used by | Configuration |
|---|---|---|---|
sqlite | sqlite | Local development, Fly.io and Docker with a volume | DATABASE_URL is a file path |
d1 | d1 | Cloudflare | The EDGE_DB binding |
postgres | postgres | Fly.io, Railway, Docker, any Node host | DATABASE_URL=postgresql://... |
hyperdrive | postgres | Cloudflare with Postgres | DATABASE_ADAPTER=hyperdrive and the HYPERDRIVE binding |
turso | sqlite | A Node host on libSQL | DATABASE_ADAPTER=turso, DATABASE_URL, DATABASE_AUTH_TOKEN |
A Worker may not reuse a socket opened for another request, so the hyperdrive adapter creates its
Postgres client per request and leaves pooling to Hyperdrive. A project can register its own adapter.
See Write a custom database adapter.
Supabase-Hosted Postgres
Supabase and Neon are hosted Postgres endpoints on the generic Drizzle Postgres adapter. The application does not use Supabase-specific APIs, client SDKs, auth helpers, storage APIs or RLS as a business dependency. Authorization stays in the server-side auth, RBAC and repository layers.
DATABASE_DIALECT=postgres
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgresSee Use Postgres and Supabase and Use Turso.
Cloudflare Workers and D1
wrangler.jsonc defines the Worker entry src/server-entry.ts, the D1 binding EDGE_DB,
DATABASE_DIALECT=d1 and the D1 migration directory ./drizzle/migrations/sqlite. D1 shares the
SQLite schema family, so it applies the same migrations as local SQLite. D1 has no interactive
transactions. Code that opens one runs its statements in sequence there.
Changing the schema
A schema change needs a matching migration in both dialects:
pnpm db:generate:sqlite --name=my-change
pnpm db:generate:postgres --name=my-change
pnpm validate:migrationspnpm db:generate:sqlite writes to drizzle/migrations/sqlite and pnpm db:generate:postgres to
drizzle/migrations/postgres. The two directories are never shared. pnpm db:generate writes a new
migration for a schema difference and does not prepare a database.
Storage over the S3-compatible protocol
Uploads, deletes and signed URLs use the S3-compatible protocol through Admin-managed S3-compatible config
in /admin/config/storage: endpoint, region, bucket, access key, secret key, an optional
CDN or public access domain, and Image/video/audio/file upload MIME categories. Cloudflare R2, Aliyun OSS, MinIO, AWS S3
and similar providers share this path.
Storage credentials are admin settings, not environment variables, so every platform configures storage the same way. On Cloudflare, the bucket binding is available as a second driver behind the same storage interface. The other platforms have no binding and use S3-compatible credentials.
External provider validation
Local validation checks state machines and missing-provider failure paths. Real provider checks need sandbox or production credentials:
pnpm validate:external-readiness
EXTERNAL_VALIDATE_STRICT=true pnpm validate:externalThe readiness report is written to openspec/EXTERNAL_VALIDATION_STATUS.json. The intentionally
unresolved OpenSpec 3.3 tasks are auth-account 3.3, billing-payment 3.3, analytics-support 3.3,
ai-workspace 3.3 and newsletter-waitlist 3.3. These remain unchecked until real Google OAuth, payment,
analytics, AI and newsletter credentials are configured.
Release guardrails
- Use
pnpm validate:allbefore release. - Use
pnpm validate:deploy-targetsafter changing a deployment template or a Dockerfile. - Use
pnpm validate:migrationsafter changing Drizzle schema or migration files. - Use
pnpm buildbefore deploy, then the smoke check for the build you ship:pnpm smoke:workerafterpnpm buildon Cloudflare,pnpm smoke:nodeafterpnpm build:nodeelsewhere. - Keep SQLite/D1 migrations in
drizzle/migrations/sqliteand Postgres migrations indrizzle/migrations/postgres. - Keep
A32-A34andA82-A98out of routes and design generation inputs. - Keep
/zhroute parity intact. - Do not add mock providers or fake provider ids, checkout URLs, payout success, email ids, AI output or analytics reports.