Kernlift

Configuration model

Why a few settings live in environment variables and everything else lives in the database, edited in the admin console.

Kernlift keeps settings in two places. A handful of environment variables start the app and connect it to the database. Everything else, including every provider credential, is stored in the database and edited in the admin console. To change settings, see Manage configuration.

The rule

SettingWhere it goesWhy
App environment, session secret, database connection, site URL.env or your host's environmentNeeded before the app can read the database
Sign-in methods, email, payments, storage, AI, analytics, cacheAdmin console, /admin/config/*Stored in the database, changed without a redeploy
Products, plans and licencesAdmin console, /admin/products and /admin/licencesBusiness data, not configuration

The split follows startup order. Anything the process needs before it can open the database comes from the environment. Everything else is stored in the database and managed by the operator.

Why provider settings are not environment variables

  • No redeploy to change a provider. Rotating a key, switching the active email provider or turning on Google sign-in takes one save in the admin console.
  • One source of truth. The /setup checklist, the admin pages and the runtime all read the same rows, so the page reports the configuration the server uses.
  • A forkable template. A project built on the template adds provider settings to the admin surface and adds no environment variable. Feature code does not read process.env.

The environment variables

A local project needs only BETTER_AUTH_SECRET, which you set in the quick start. Production sets these:

VariableRole
APP_ENVdevelopment or production. Production enables stricter checks
BETTER_AUTH_SECRETSigns sessions. Production refuses to start with the template default
CONFIG_ENCRYPTION_KEYOptional, strongly recommended. Encrypts the credentials stored in the database; see Encrypt stored credentials
DATABASE_DIALECTsqlite, postgres or d1
DATABASE_ADAPTEROptional adapter id such as turso or a custom adapter. Defaults to the dialect
DATABASE_URLFile path or connection string
SITE_URLCanonical origin for metadata, the sitemap, the feed and email links

.env.example lists every variable the source reads, and pnpm validate:env-example keeps the two in step. Every variable is described in Environment variables.

The admin settings pages

PageCovers
/admin/config/authEmail and password rules, Google and GitHub OAuth, Google One Tap, the sign-up bonus
/admin/config/emailResend, Cloudflare Email or Aliyun DirectMail, and notification webhooks
/admin/config/paymentStripe, Creem, PayPal, DodoPayments, WeChat Pay, Alipay or Waffo, success and cancel URLs, promotion codes
/admin/config/storageS3-compatible storage and allowed upload types
/admin/config/aiAI providers, provider scenes, scenes and credit pricing
/admin/config/analyticsAnalytics provider
/admin/config/cacheCache enable, TTL and backend per domain
/admin/config/sandboxAgent sandbox provider, image and resource limits; installed with agent-starter
/admin/config/searchAgent search and crawl services; installed with agent-starter

Newsletter, notification channels and rate limits have separate admin pages. The complete route and permission map is in Manage configuration.

"Not configured" is a state, not an error

A provider without credentials reports "not configured" and does not run. The template never fakes a provider response, simulates a payment or invents usage data. /setup turns those states into a checklist: each item is Ready or Not ready, and Configure links to the page that fixes it. Only the session secret, a sign-in method and email delivery are required.

Encrypt stored credentials

Credentials live in the database, so a leaked backup, read replica or database console would expose them. Set CONFIG_ENCRYPTION_KEY (at least 32 characters) in the environment of every process that reads the config table, the web app and, when deployed, the Agent service, and every setting classified secret is encrypted at rest:

  • What is encrypted. Values classified secret: payment, email, storage, AI and OAuth credentials. They are written as enc:v1:<iv>:<ciphertext> with AES-256-GCM, the key derived with HKDF-SHA-256 and the setting key bound as additional data, so a ciphertext cannot be moved to another row. public and internal values stay plaintext.
  • Existing credentials. A credential saved before the key was set stays plaintext until it is saved again. Run pnpm db:encrypt-config-secrets once to encrypt them all; on D1 add --remote for the deployed database. A second run changes nothing.
  • A wrong or missing key. A value that cannot be decrypted reads as not configured, never as ciphertext, and seeding never overwrites it, so restoring the right key restores the credential.
  • Caches. Cache domains that hold decrypted credentials always use process memory; KV or Redis cannot be chosen for them on /admin/config/cache.
  • Readiness. /setup has a Credential encryption item. It reports a missing or too short key, plaintext credentials left over and credentials that cannot be decrypted; only the last makes it required.

Without the key, credentials are stored as plaintext and everything else behaves the same, which suits local development. kernlift deploy-target generates the key into .env.production. Keep the key stable: there is no rotation, and changing or losing it means entering every credential again.

How settings are read

Most configuration reads are cached. Saving through the console clears the relevant domain. A direct database edit may remain unseen until its TTL expires. The bootstrap admin_config cache cannot read its own policy from the table it caches, so its TTL comes from ADMIN_CONFIG_CACHE_TTL_MS. /admin/config/cache marks that domain as not configurable.

Variables outside the application

The KERNLIFT_* variables at the end of .env.example are read only by the registry publishing script and the CLI's package commands. The application never reads them, and a project cloned from GitHub can leave them unset.

Files

src/server/db/repositories/admin-config.repository.ts
src/server/config/config-encryption.ts
scripts/db/encrypt-config-secrets.ts
src/server/platform/cache-policy.ts
src/routes/{-$locale}/admin/config
src/components/admin/config-layout.tsx

The pages use shared console patterns, but their data is not all stored alike: ordinary provider settings use classified config_settings rows, AI channels and pricing use dedicated tables, and Agent search uses JSON rows classified as secret.

Next steps