Skip to content

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
A pale gradient of blue and cyan, in upright folds like a curtain

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 get

  • 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

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 button

  1. Under kaeso-gateway, fill in these variables:

    VariableWhat 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_PORT587 unless your server uses another port
    KAESO_CLICKHOUSE_URLA ClickHouse HTTP URL with user and password for request logs, or empty

    The template fills in the rest: KAESO_MASTER_KEYS with 32 random bytes from Railway's secret() function, and KAESO_PUBLIC_URL with the edge's Railway domain.

  2. Deploy, and wait until the five services are online.

  3. Open the one-time setup link the gateway emailed you, and create the first user.

  4. Copy KAESO_MASTER_KEYS from the variables of kaeso-gateway into 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 CLI

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 generate

Then create an empty project:

railway loginrailway init

In 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 apply

Give 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 domain

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 back

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 tested

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 steps

By Kaeso Team

On this page

Own the gateway.Own the record.

curl -fsSLhttps://kaeso.app/install.sh | sh