Kernlift

Quick start

Clone the repository, install it, build the database, create the administrator and run the project locally.

This page takes you from an activated purchase to a local project you are signed in to as administrator. It uses a local SQLite file, so you need no database server and no cloud account. A business template is installed the same way; only the repository address differs.

Before you begin

  • The tools in Prerequisites: Node 22.12 or later in the 22.x line, pnpm and git.
  • An activated purchase and an accepted GitHub invitation. See Get Kernlift.
  • About ten minutes. Most of it is pnpm install.

Run it locally

Clone the repository

git clone git@github.com:kernlift/kernlift.git my-app
cd my-app

For a business template, clone kernlift/<template-key> instead. The exact address is on the Purchased templates page (/app/licences).

If git answers "Repository not found", the invitation has not been accepted yet, or git is using another GitHub account.

Install dependencies and generate types

pnpm install
pnpm cf-typegen

pnpm cf-typegen writes worker-configuration.d.ts, the runtime type declarations. The file is generated and is not committed, so pnpm typecheck fails on a fresh clone until it exists. It works with or without a wrangler.jsonc; on a Cloudflare project, run it again whenever you change a binding.

Create your .env

cp .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Paste the printed value into BETTER_AUTH_SECRET in .env. For local work this is the only value you need to set: the file already points DATABASE_DIALECT at sqlite and DATABASE_URL at ./local.db.

.env.example marks each variable: [必填] must be set, [可选] has a working default, [开发] applies only to development.

Build the database

pnpm db:migrate

This applies the migration chain and records each step. When it finishes, local.db exists in the project root. It is the only supported way to build the schema.

Create the first administrator

SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<at least 8 characters>' pnpm db:bootstrap-super-admin

You should see Created the super administrator you@example.com (sqlite)., then a Baseline content: line counting what it inserted. Running it again is safe: it never overwrites a row an administrator edited.

Besides the administrator, this writes the permission set, the super admin role and the baseline content (email templates, marketing pages, /system state pages, notification channels and rate-limit rules). There is no demo data.

Start the app

pnpm dev

Vite prints the local address, http://localhost:5173 by default. Leave it running.

Sign in

Open /auth/sign-in and sign in with the administrator email and password from the previous step. You are signed in as the super administrator, so the admin console at /admin opens for you.

What the install produced

src/routes
src/server
src/components
drizzle/migrations/sqlite
drizzle/migrations/postgres
modules
scripts/validate

The route generator refreshes src/routeTree.gen.ts when you run pnpm dev or pnpm build. pnpm typecheck fails until one of them has run once.

Push it to your own repository

The repository you cloned is read-only and cannot be forked. Create an empty private repository on GitHub and make it origin:

git remote set-url origin git@github.com:YOUR-ACCOUNT/my-app.git
git push origin main

To take later updates, add the template repository back as upstream. See Sync upstream updates.

Set the deployment target

A clone carries deploy.config.json and the deployment files of one platform. You do not need to touch them for local work. To deploy somewhere else, or to add the agent service, run:

pnpm kernlift deploy-target fly --no-agent --dialect sqlite

Replace fly with cloudflare, railway or docker. The command writes that platform's files, moves the previous ones to .kernlift/previous-deploy/, generates the production secrets into .env.production and prints the remaining steps. It creates nothing remote. The platforms and the databases each allows are listed in the Deployment configuration.

Verify

Open /setup. Session secret and Sign-in method show Ready; Email delivery shows Not ready until you connect a provider. That is the expected state of a fresh project.

Troubleshooting

git clone says "Repository not found"

GitHub answers this for a private repository you cannot read. Accept the invitation from your GitHub notifications, and check that the SSH key or credential git uses belongs to the account you activated the purchase with. If the invitation expired, see My invitation expired.

pnpm typecheck reports missing routes

The route generator refreshes src/routeTree.gen.ts when you run pnpm dev or pnpm build. then type-check again.

pnpm typecheck fails on the Cloudflare bindings

worker-configuration.d.ts is missing or out of date, for example after you changed wrangler.jsonc. Run pnpm cf-typegen.

The database exists but was not built by pnpm db:migrate

The migration runner reads its own history to work out which migrations to apply, so a database created another way cannot be migrated in place. Delete local.db and run pnpm db:migrate again. The reasoning is in Runtimes and database adapters.

Next steps