Kernlift

Run the Node build

Build the Node server with pnpm build:node or the root Dockerfile, give it its environment, migrate, and run it on any host.

Every platform except Cloudflare runs the same Node server. pnpm build:node produces it, the root Dockerfile packages it, and Fly.io, Railway and Docker Compose each deploy that image with a generated configuration. Use this guide to understand what the build contains, or to run it on a host that has no platform guide. For the three supported platforms, follow Deploy to Fly.io, Deploy to Railway or Deploy with Docker Compose instead.

Before you begin

  • A host with Node 22, or Docker.
  • A database: Postgres (see Use Postgres and Supabase), or a SQLite file on a disk that survives restarts, for a single instance.
  • A session secret. .env.production, generated by kernlift deploy-target, already holds one.

What the build produces

PathContents
.output/server/index.mjsThe server. pnpm start runs it; it listens on PORT, 3000 in the image
.output/scripts/bootstrap-super-admin.mjsCreates the administrator against the deployment's own database, without a TypeScript runner
scripts/db/migrate-runtime.mjsApplies the migration chain with plain Node
drizzle/migrations/The SQLite and Postgres chains the migrator reads

The root Dockerfile runs pnpm build:node and copies these four into a node:22 image, together with the database drivers (better-sqlite3, postgres, drizzle-orm), which are loaded by name at run time and are not part of the bundle. It runs as the node user, exposes port 3000 and provides /data for a SQLite file on a mounted volume. The agent service is a separate image, apps/agent-service/Dockerfile.

pnpm build produces this build when deploy.config.json names fly, railway or docker. pnpm build:node always produces it.

Environment

The server reads its settings from the process environment.

VariableValue
APP_ENVproduction
PORTThe port to listen on
BETTER_AUTH_SECRETThe session secret from .env.production
CONFIG_ENCRYPTION_KEYThe credential encryption key from .env.production; keep it stable
SITE_URLThe canonical origin for metadata and absolute links
DATABASE_DIALECTpostgres or sqlite
DATABASE_URLA postgresql:// URL, or a file path such as /data/app.db
JOBS_IN_PROCESSLeave unset. false turns off the scheduled-jobs loop; an external cron must then call pnpm jobs:run
AGENT_SERVICE_URL, AGENT_INTERNAL_SIGNING_SECRETOnly with the agent service: its private address and the shared signing secret

No provider credentials go here; see Manage configuration. All variables are described in Environment variables.

Build and run

Build

From a checkout:

pnpm install
pnpm build:node

Or build the image from the repository root:

docker build -t kernlift-web .

Apply the migrations

With DATABASE_DIALECT and DATABASE_URL set, run the migrator before the new version takes traffic:

node scripts/db/migrate-runtime.mjs

It keeps the same bookkeeping table as pnpm db:migrate, so either can be used on the same database.

Start the server

node .output/server/index.mjs

This is also the image's default command. The scheduled jobs start with the process and run a round every minute. When several replicas run, a lock row in the config table limits each round to one replica.

Create the administrator

In the same environment as the server:

node .output/scripts/bootstrap-super-admin.mjs

It prompts for the email and the password, and does not echo the password. Without a terminal, set SUPER_ADMIN_EMAIL and SUPER_ADMIN_PASSWORD in the environment instead.

Configure runtime services

Sign in and open /setup. Enter S3-compatible credentials in /admin/config/storage. The bucket binding driver exists only on Cloudflare. At /admin/config/cache the backend is process memory, one cache per process. See Set up file storage and uploads and Cache.

Verify

  • /setup shows Session secret and Scheduled jobs as ready; the second one needs a minute or two after the first start.
  • In the repository, pnpm smoke:node after pnpm build:node starts the build on a throwaway SQLite database and checks that pages render, the agent API returns 503 without the agent service, and a scheduled round is recorded.
  • pnpm validate:deploy-targets checks that the image runs the Node build and carries the migrations and the migrator.

Troubleshooting

.output/server/index.mjs is missing

The last build was the Cloudflare one, which writes dist/. Run pnpm build:node.

DATABASE_URL is required when DATABASE_ADAPTER=postgres

DATABASE_DIALECT is postgres but DATABASE_URL is empty. Set the connection string.

The server refuses to start with a session secret error

APP_ENV is not development and BETTER_AUTH_SECRET is missing or the template default. Set the generated value.

Scheduled jobs stay not ready on /setup

The web process is stopped, or JOBS_IN_PROCESS=false is set and nothing calls pnpm jobs:run.

Next steps