Kernlift

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.

On a Docker host the project is a compose stack: a migrate service that applies the migrations and exits, the web service built from the root Dockerfile, and either a SQLite file on a volume or a bundled Postgres. The agent service is optional and runs as a compose service, on Postgres only. Nothing remote is created. Use this guide for the first deployment on a server you manage.

Before you begin

  • A server with Docker and Docker Compose (docker compose version prints a version), and the project checked out on it.
  • deploy.config.json says "platform": "docker". Run pnpm kernlift deploy-target docker to set it, with --dialect sqlite, --dialect postgres or --agent as needed. See deploy.config.json.
  • compose.yaml and .env.production in the project root; that command writes them. .env.production is not committed, so copy it to the server yourself.
  • A domain pointing at the server, and a reverse proxy that terminates TLS.

Prepare the values

Set the public URL

In .env.production, set SITE_URL to the public address, for example https://your-domain.com. Without it the web service falls back to http://localhost:3000. On first start the app also seeds the auth Base URL from it, so OAuth callbacks and email links would point there.

Check the generated secrets

The same file must hold BETTER_AUTH_SECRET and CONFIG_ENCRYPTION_KEY, and POSTGRES_PASSWORD when the database is Postgres. With the agent it also holds AGENT_INTERNAL_SIGNING_SECRET and AGENT_RESOURCE_GRANT_SECRET. Compose fails to start when one of them is missing. To add missing keys without changing existing ones, run pnpm kernlift deploy-target docker again.

Start the stack

Build, migrate and start

pnpm run deploy

The script runs:

docker compose --env-file .env.production up -d --build

The migrate service runs node scripts/db/migrate-runtime.mjs first; web starts only after it succeeds. With Postgres, migrate waits for the postgres service to be healthy.

Put TLS in front

The web service publishes port 3000. Point your reverse proxy at it and serve the site over HTTPS on the address you put in SITE_URL.

Create the production administrator

docker compose --env-file .env.production exec web node .output/scripts/bootstrap-super-admin.mjs

The script runs inside the web container, against its own database, and prompts for the email and password.

Where the data lives

DatabaseServiceVolume
sqliteNone; web opens /data/app.dbdata
postgrespostgres, image postgres:16-alpine, user and database kernliftpgdata

Back these volumes up. Removing them removes the database. Files uploaded by users are not stored on the server. Configure S3-compatible storage in /admin/config/storage; see Set up file storage and uploads.

With "agent": true, the stack also has an agent service built from apps/agent-service/Dockerfile. The web service reaches it at http://agent:3001 on the compose network. The agent publishes no port. Run one instance, because it holds run state in memory.

Deploy a new version

Pull the new code and run pnpm run deploy again. The images are rebuilt, migrate applies any new migrations, and web is replaced after it succeeds.

Verify

  • docker compose ps shows web running and migrate exited successfully.
  • The site loads over HTTPS at your domain.
  • /setup, signed in as the administrator, names Docker and the database in its first line and shows Session secret as ready.
  • /admin/config/auth shows the Base URL the site answers on. Change it there if the site uses another domain.
  • Scheduled jobs turns ready within a couple of minutes. The jobs run inside the web container.
  • With the agent, /app/agent opens the workbench.
  • In the repository, pnpm smoke:node after pnpm build:node checks the build you ship, and pnpm validate:deploy-targets checks the rendered compose.yaml.

Troubleshooting

Compose stops with set BETTER_AUTH_SECRET, set CONFIG_ENCRYPTION_KEY or set POSTGRES_PASSWORD

The value is missing from .env.production, or the command ran without --env-file .env.production. Use pnpm run deploy.

The Base URL at /admin/config/auth still holds the fallback address. Correct it there. Also set SITE_URL in .env.production and run pnpm run deploy again so metadata and absolute links use the public address.

web never starts

migrate failed. Read its output with docker compose logs migrate.

Scheduled jobs stay not ready on /setup

Check that the web container is up with docker compose ps. If JOBS_IN_PROCESS=false is set, an external cron has to run pnpm jobs:run instead.

Next steps