---
title: Deploy Kaeso on Railway
description: "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."
url: https://kaeso.app/articles/deploy-kaeso-on-railway
markdown: https://kaeso.app/articles/deploy-kaeso-on-railway.md
language: en
alternates:
  de: https://kaeso.app/de/articles/deploy-kaeso-on-railway.md
  zh-CN: https://kaeso.app/zh-CN/articles/deploy-kaeso-on-railway.md
published: 2026-11-11
authors:
  - Kaeso Team
tags:
  - self-hosting
  - railway
  - deployment
  - guide
image: https://kaeso.app/articles/deploy-kaeso-on-railway/cover.jpg
index: https://kaeso.app/llms.txt
---

# 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.

> Every page, article and docs page of Kaeso is listed in https://kaeso.app/llms.txt.

- Published: 11 November 2026
- 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 get

| 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 button

1. Open [Deploy on Railway](https://railway.com/deploy/cmVV60) and sign in.
2. Under `kaeso-gateway`, fill in these variables:

   | Variable | What to enter |
   | --- | --- |
   | `KAESO_SETUP_EMAIL` | Your address; the gateway emails the setup link there |
   | `KAESO_SMTP_HOST`, `KAESO_SMTP_FROM` | Your SMTP server and the sender of Kaeso's emails |
   | `KAESO_SMTP_USER`, `KAESO_SMTP_PASSWORD` | The server's user name and password, if it needs them |
   | `KAESO_SMTP_PORT` | `587` unless your server uses another port |
   | `KAESO_CLICKHOUSE_URL` | A 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.

3. Deploy, and wait until the five services are online.
4. Open the one-time setup link the gateway emailed you, and create the first user.
5. 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:

```bash
docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate
```

Then create an empty project:

```bash
railway login
railway 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`](https://github.com/logicplanes/kaeso/blob/v0.6.0/.railway/railway.ts) in a folder of your own, install Railway's TypeScript package and apply it:

```bash
npm install railway
railway 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

- [Railway in the docs](https://docs.kaeso.app/self-hosting/platforms/railway), with every variable.
- [Backups and master keys](https://docs.kaeso.app/self-hosting/backups): back up Railway Postgres and keep the master key outside Railway.
- [Where to run Kaeso](https://kaeso.app/articles/where-to-run-kaeso): how Railway compares with the other platforms.

By Kaeso Team

## More articles

- [Deploy Kaeso on Render](https://kaeso.app/articles/deploy-kaeso-on-render.md): Run Kaeso on Render from the blueprint in the repository, with a public edge, a private gateway and console, Render Postgres and Key Value. Step by step, from the master key to your own domain.
- [Deploy Kaeso on DigitalOcean](https://kaeso.app/articles/deploy-kaeso-on-digitalocean.md): Run Kaeso on DigitalOcean App Platform with the Deploy to DigitalOcean button, or with doctl and a managed Valkey for production. The app's own edge routes the console and the APIs on one domain.

[See all articles](https://kaeso.app/articles.md)

## Own the gateway. Own the record

```bash
curl -fsSL https://kaeso.app/install.sh | sh
```

[Install Kaeso](https://docs.kaeso.app/self-hosting/installation) · [Open the live demo](https://demo.kaeso.app)
