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
railwayCLI, signed in (railway login). deploy.config.jsonsays"platform": "railway". Runpnpm kernlift deploy-target railwayto set it, with--agentif you want the agent service. See deploy.config.json..railway/railway.tsand.env.productionin 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-saasApply the configuration
railway config apply --yesThis 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 uppnpm 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 webThen run the script the image carries. It prompts for the email and password:
node .output/scripts/bootstrap-super-admin.mjsScheduled 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 upVerify
- The site loads at the public address of the
webservice. /setup, signed in as the administrator, names Railway and Postgres 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.
- With the agent,
/app/agentopens the workbench. - In the repository,
pnpm smoke:nodeafterpnpm build:nodechecks the build you ship, andpnpm validate:deploy-targetschecks 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.
OAuth sign-in or email links point at the wrong address
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
Deploy to Fly.io
Create the Fly app, import the generated secrets, deploy the Node image with migrations, create the production administrator, and optionally add the agent app.
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.