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-appFor 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-typegenpnpm 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:migrateThis 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-adminYou 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 devVite 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
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 mainTo 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 sqliteReplace 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.