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 bykernlift deploy-target, already holds one.
What the build produces
| Path | Contents |
|---|---|
.output/server/index.mjs | The server. pnpm start runs it; it listens on PORT, 3000 in the image |
.output/scripts/bootstrap-super-admin.mjs | Creates the administrator against the deployment's own database, without a TypeScript runner |
scripts/db/migrate-runtime.mjs | Applies 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.
| Variable | Value |
|---|---|
APP_ENV | production |
PORT | The port to listen on |
BETTER_AUTH_SECRET | The session secret from .env.production |
CONFIG_ENCRYPTION_KEY | The credential encryption key from .env.production; keep it stable |
SITE_URL | The canonical origin for metadata and absolute links |
DATABASE_DIALECT | postgres or sqlite |
DATABASE_URL | A postgresql:// URL, or a file path such as /data/app.db |
JOBS_IN_PROCESS | Leave unset. false turns off the scheduled-jobs loop; an external cron must then call pnpm jobs:run |
AGENT_SERVICE_URL, AGENT_INTERNAL_SIGNING_SECRET | Only 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:nodeOr 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.mjsIt 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.mjsThis 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.mjsIt 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
/setupshows Session secret and Scheduled jobs as ready; the second one needs a minute or two after the first start.- In the repository,
pnpm smoke:nodeafterpnpm build:nodestarts 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-targetschecks 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
Deploy with Docker Compose
Run the project on your own server with compose.yaml: set the public URL, start the stack with migrations, put TLS in front, and create the production administrator.
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.