Deploy Kaeso on Railway
Run Kaeso on Railway with the Deploy on Railway button, which generates the master key for you, or from the infrastructure file with the Railway CLI. Five services, one public edge, Railway Postgres and Redis.
- Published
- Reading time
- 3 min
- Author
- Kaeso Team

Railway is the quickest way to try Kaeso on a platform: the Deploy on Railway button creates the whole project, generates the master key and fills in the public address. You enter your email and an SMTP server, and wait for five services to come online.
For teams that keep their infrastructure in code, the repository also has .railway/railway.ts, the same project in Railway's TypeScript format, for the Railway CLI.
What you get01
kaeso-edge- Image
- The console image, running
kaeso-edge - Reached by
- Everyone, on its Railway domain or your own
kaeso-gateway- Image
- The gateway image
- Reached by
- The edge, on Railway's private network
kaeso-console- Image
- The console image
- Reached by
- The edge, on Railway's private network
kaeso-postgres- Image
- Railway Postgres
- Reached by
- The gateway
kaeso-valkey- Image
- Railway Redis
- Reached by
- The gateway
| Service | Image | Reached by |
|---|---|---|
kaeso-edge | The console image, running kaeso-edge | Everyone, on its Railway domain or your own |
kaeso-gateway | The gateway image | The edge, on Railway's private network |
kaeso-console | The console image | The edge, on Railway's private network |
kaeso-postgres | Railway Postgres | The gateway |
kaeso-valkey | Railway Redis | The gateway |
Railway's private network is IPv6 only, so the gateway listens on [::]:8080 and trusts the edge from the unique local address range. Each service sets PORT to the port it listens on, which Railway's health checks call. Automatic image updates are off, so the services stay on the release they were deployed with.
Deploy with the button02
- 01
Open Deploy on Railway (opens in a new tab) and sign in.
- 02
Under
kaeso-gateway, fill in these variables:Variable What to enter KAESO_SETUP_EMAILYour address; the gateway emails the setup link there KAESO_SMTP_HOST,KAESO_SMTP_FROMYour SMTP server and the sender of Kaeso's emails KAESO_SMTP_USER,KAESO_SMTP_PASSWORDThe server's user name and password, if it needs them KAESO_SMTP_PORT587unless your server uses another portKAESO_CLICKHOUSE_URLA ClickHouse HTTP URL with user and password for request logs, or empty The template fills in the rest:
KAESO_MASTER_KEYSwith 32 random bytes from Railway'ssecret()function, andKAESO_PUBLIC_URLwith the edge's Railway domain. - 03
Deploy, and wait until the five services are online.
- 04
Open the one-time setup link the gateway emailed you, and create the first user.
- 05
Copy
KAESO_MASTER_KEYSfrom the variables ofkaeso-gatewayinto a password manager. Kaeso encrypts provider keys with it, so a database backup can't be read without it.
The gateway doesn't start without an SMTP server, and its image has no shell, so railway ssh can't print a setup link. If the email doesn't arrive, the gateway's logs name the SMTP error. Correct the variables and redeploy the gateway: it sends a new link at every start while no user exists.
Deploy with the CLI03
Generate a master key first, and keep it in a password manager:
docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generateThen create an empty project:
railway loginrailway initIn the project's Settings, under Shared Variables, add KAESO_PUBLIC_URL (a placeholder for now), KAESO_MASTER_KEYS, KAESO_SETUP_EMAIL, your SMTP server's KAESO_SMTP_* values and, for request logs, KAESO_CLICKHOUSE_URL.
Put the release's .railway/railway.ts (opens in a new tab) in a folder of your own, install Railway's TypeScript package and apply it:
npm install railwayrailway config applyGive kaeso-edge a domain under its Settings, for port 8080. Set KAESO_PUBLIC_URL to https:// and that domain, and redeploy kaeso-gateway; the setup link arrives by email.
Railway marks infrastructure as code as experimental, so its API can still change. Railway's older railway.json and railway.toml stop working on 2026-12-01, which is why the repository has neither.
Your own domain04
Add the domain to kaeso-edge under Settings, set KAESO_PUBLIC_URL on kaeso-gateway to https:// and that domain, and redeploy the gateway.
Update and roll back05
For a project from the button, change the image tag of kaeso-gateway, kaeso-console and kaeso-edge under each service's Settings to the new release, gateway first. For a project from the file, apply the new release's railway.ts, and Railway redeploys what changed. The gateway migrates the database at start, forward only. To roll back, redeploy an earlier deployment from a service's Deployments list.
What was tested06
On 2026-11-09, the file was applied to an empty Railway project and the template deployed into another one, both with the eighth release candidate. In both, the five services came online, the edge served the console and the APIs on the Railway domain, and the first user was set up and signed in. That run found the missing PORT, which the file and the template now set. Email delivery, a streamed reply and an update haven't been tested on Railway yet.
Next steps07
- Railway in the docs (opens in a new tab), with every variable.
- Backups and master keys (opens in a new tab): back up Railway Postgres and keep the master key outside Railway.
- Where to run Kaeso: how Railway compares with the other platforms.
By Kaeso Team


