Kernlift

Deploy to Railway

Create the Railway project, services and Postgres from .railway/railway.ts, set the generated secrets, deploy, and create the production administrator.

On Railway the project is a web service built from the root Dockerfile and a Postgres database, both declared in .railway/railway.ts. The agent service is optional and runs as a second service named agent. Use this guide for the first production deployment.

Before you begin

  • The railway CLI, signed in (railway login).
  • deploy.config.json says "platform": "railway". Run pnpm kernlift deploy-target railway to set it, with --agent if you want the agent service. See deploy.config.json.
  • .railway/railway.ts and .env.production in the project root; that command writes them.

Railway projects run on Postgres. You do not need to prepare a database. The configuration declares one and passes its DATABASE_URL to the services.

Create the project

kernlift deploy-target railway prints these two steps for your project.

Create the Railway project

railway init --name my-saas

Apply the configuration

railway config apply --yes

This creates the web service, the Postgres database and, with the agent, the agent service. railway config plan shows the changes first without applying them.

Store the secrets and deploy

Set the public URL

In .env.production, set SITE_URL to the public address of the web service: your own domain, or the one Railway assigns.

Set the variables on the web service

The commands read each value from .env.production, so you type no secret on the command line.

railway variables --service web --set "BETTER_AUTH_SECRET=$(grep '^BETTER_AUTH_SECRET=' .env.production | cut -d= -f2-)"
railway variables --service web --set "CONFIG_ENCRYPTION_KEY=$(grep '^CONFIG_ENCRYPTION_KEY=' .env.production | cut -d= -f2-)"
railway variables --service web --set "SITE_URL=$(grep '^SITE_URL=' .env.production | cut -d= -f2-)"

Set secrets this way. Do not write them into .railway/railway.ts.

Deploy

railway up

pnpm run deploy runs the same command. The web service's pre-deploy step runs node scripts/db/migrate-runtime.mjs, so the migrations are applied before the new version takes traffic.

Create the production administrator

Open a shell in the web service:

railway ssh --service web

Then run the script the image carries. It prompts for the email and password:

node .output/scripts/bootstrap-super-admin.mjs

Scheduled jobs need a running web service

The scheduled jobs run inside the web service. If the service is not running, no fulfilment retries or AI task polling happen until it is.

Add the agent service

Skip this section if the project does not include the agent. With "agent": true, .railway/railway.ts declares an agent service with one replica, built from apps/agent-service/Dockerfile, and points the web service at http://agent.railway.internal:3001.

Set the agent secrets

railway variables --service web --set "AGENT_INTERNAL_SIGNING_SECRET=$(grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2-)"
railway variables --service agent --set "AGENT_INTERNAL_SIGNING_SECRET=$(grep '^AGENT_INTERNAL_SIGNING_SECRET=' .env.production | cut -d= -f2-)"
railway variables --service agent --set "AGENT_RESOURCE_GRANT_SECRET=$(grep '^AGENT_RESOURCE_GRANT_SECRET=' .env.production | cut -d= -f2-)"

Deploy

railway up

Verify

  • The site loads at the public address of the web service.
  • /setup, signed in as the administrator, names Railway and Postgres 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.
  • 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 .railway/railway.ts.

Troubleshooting

The web service refuses to start with a session secret error

BETTER_AUTH_SECRET is not set on the web service. Run the railway variables command again and redeploy.

The Base URL at /admin/config/auth does not match the public address. Correct it there; no redeploy is needed.

Scheduled jobs stay not ready on /setup

Check that the web service is running. If JOBS_IN_PROCESS=false is set, an external cron has to run pnpm jobs:run instead.

TypeScript reports errors in .railway/railway.ts

The file starts with @ts-nocheck because the railway CLI type-checks it and this project does not. Keep that line.

Next steps