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 versionprints a version), and the project checked out on it. deploy.config.jsonsays"platform": "docker". Runpnpm kernlift deploy-target dockerto set it, with--dialect sqlite,--dialect postgresor--agentas needed. See deploy.config.json.compose.yamland.env.productionin the project root; that command writes them..env.productionis 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 deployThe script runs:
docker compose --env-file .env.production up -d --buildThe 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.mjsThe script runs inside the web container, against its own database, and prompts for the email and password.
Where the data lives
| Database | Service | Volume |
|---|---|---|
sqlite | None; web opens /data/app.db | data |
postgres | postgres, image postgres:16-alpine, user and database kernlift | pgdata |
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 psshowswebrunning andmigrateexited 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/authshows 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/agentopens the workbench. - In the repository,
pnpm smoke:nodeafterpnpm build:nodechecks the build you ship, andpnpm validate:deploy-targetschecks the renderedcompose.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.
OAuth sign-in or email links point at localhost:3000
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
Deploy to Railway
Create the Railway project, services and Postgres from .railway/railway.ts, set the generated secrets, deploy, and create the production administrator.
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.