Kernlift

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

deploy.config.json
{
  "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

TargetPlatformsServer entryOutputStarted by
cloudflareCloudflaresrc/server-entry.tsdist/wrangler deploy
nodeFly.io, Railway, Dockersrc/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

CloudflareFly.ioRailwayDocker
Database without the agentD1 or Postgres through HyperdrivePostgres or SQLite on a volumePostgresPostgres or SQLite on a volume
Database with the agentPostgres through HyperdrivePostgresPostgresPostgres
Agent serviceCloudflare containerThe <name>-agent appThe agent serviceThe agent compose service
Object storageR2 binding or S3-compatibleS3-compatibleS3-compatibleS3-compatible
CacheKV or process memoryProcess memoryProcess memoryProcess 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.

PlatformWhat applies the migrations
Cloudflare with D1pnpm db:migrate:d1:remote, run before pnpm run deploy
Cloudflare with Postgrespnpm db:migrate from the checkout, against the Postgres URL
Fly.io with Postgresrelease_command in fly.toml, on a temporary machine
Fly.io with SQLiteThe app process, before the server starts; a release machine has no volume
RailwayThe preDeploy step of the web service
DockerThe 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.jsonc calls the Worker's scheduled handler.
  • 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.db
pnpm db:migrate
SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin
pnpm dev

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

AdapterDialectUsed byConfiguration
sqlitesqliteLocal development, Fly.io and Docker with a volumeDATABASE_URL is a file path
d1d1CloudflareThe EDGE_DB binding
postgrespostgresFly.io, Railway, Docker, any Node hostDATABASE_URL=postgresql://...
hyperdrivepostgresCloudflare with PostgresDATABASE_ADAPTER=hyperdrive and the HYPERDRIVE binding
tursosqliteA Node host on libSQLDATABASE_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/postgres

See 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:migrations

pnpm 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:external

The 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:all before release.
  • Use pnpm validate:deploy-targets after changing a deployment template or a Dockerfile.
  • Use pnpm validate:migrations after changing Drizzle schema or migration files.
  • Use pnpm build before deploy, then the smoke check for the build you ship: pnpm smoke:worker after pnpm build on Cloudflare, pnpm smoke:node after pnpm build:node elsewhere.
  • Keep SQLite/D1 migrations in drizzle/migrations/sqlite and Postgres migrations in drizzle/migrations/postgres.
  • Keep A32-A34 and A82-A98 out of routes and design generation inputs.
  • Keep /zh route parity intact.
  • Do not add mock providers or fake provider ids, checkout URLs, payout success, email ids, AI output or analytics reports.

Files

deploy.config.json
vite.config.ts
src/server/platform/deployment.ts
src/server-entry.ts
src/server-entry.node.ts
Dockerfile
apps/agent-service/Dockerfile

Next steps