Skip to content

Where to run Kaeso, from one server to a managed cloud

Kaeso 0.6.0 runs on your own server with one command, and on ten platforms from templates in the repository. A guide to the four kinds of path, what each one keeps the same, and which to choose.

Published
Reading time
4 min
Author
Kaeso Team
A deep gradient of orchid and pink, in gentle level folds

Kaeso is a gateway you run yourself, so the first question is where. Until 0.6.0 the answer was a server with Docker. Now there are eleven: your own server with one command, and ten platforms with templates in the Kaeso repository (opens in a new tab), each pinned to a release.

This guide sorts them by the kind of path they are, says what every path keeps the same, and helps you pick one. Each platform has a guide of its own, linked below.

Your own server, in one command

On any Linux server or Mac with a public domain:

curl -fsSL https://kaeso.app/install.sh | sh -s -- --domain kaeso.example.com

The installer downloads the newest release into ./kaeso, writes its settings and master key, and starts the Compose package: the gateway, the console, PostgreSQL, ClickHouse, Valkey, Caddy for TLS, and the updater. It starts Docker when it is stopped, installs it on Linux when you ask, checks the domain's DNS record and certificate, and prints the link that creates the first user. Update in the console works from the first start.

This is the path most installs should take. Everything below runs the same release on someone else's infrastructure.

Four kinds of path

  • Platform template
    What it is
    Files the platform reads: a public edge, a private gateway and console, and the platform's PostgreSQL and Valkey
  • Quick server
    What it is
    One virtual machine with the Compose package, as on your own server
  • Managed production
    What it is
    The cloud's containers, load balancer, PostgreSQL and Valkey, with secrets in its secret store
    Platforms
    AWS, Google Cloud
  • Self-hosted platform
    What it is
    A Compose file or one-click app on your own server, behind the platform's proxy

Which one to choose

  • You want it running without a server of your own: a platform template. Render and Railway create everything from a button; DigitalOcean too, with an in-app Valkey.
  • You want the full Compose package, with the updater and request logs in a bundled ClickHouse, on a cloud account you already have: a quick server on AWS, Azure or Google Cloud.
  • You expect real traffic and want the cloud to keep the databases: the managed stacks on AWS (ECS Fargate, RDS, ElastiCache) or Google Cloud (Cloud Run, Cloud SQL, Memorystore). They take a region, a domain, a certificate and sizes, so they are not one click.
  • You already run Coolify, Dokploy or CapRover: use their templates, and Kaeso lives beside your other apps.

What every path keeps the same

Whatever you choose, an install behaves the same way:

  • One origin. The console and the APIs answer on one domain. /v1, /v1beta, /v2, /platform, /mcp, /oauth and /.well-known/oauth-* reach the gateway, every other path the console. On most platforms kaeso-edge, a second command in the console image, does this routing; on DigitalOcean the app's ingress rules, on the managed stacks the load balancer, on a quick server Caddy.
  • Streams stay unbuffered. The edge flushes every chunk, and load balancers wait longer than the gateway's keepalive interval.
  • Client addresses are believed only from the platform's proxy. The edge reads the address from a header the proxy sets and can't be forged by a caller, and the gateway trusts only the edge.
  • Health checks use /healthz for the process and /readyz for PostgreSQL, Valkey and ClickHouse. The metrics port is never public.
  • One version. Gateway, console and edge are pinned to the same release, and a release updates the templates.

On platforms, Kaeso's own updater is off: the platform rolls a release out and back. A release's database migrations only move forward, so a rollback past one stays where it is, as on any install.

What every path needs

NeedHow
A master keydocker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate, kept in the platform's secret store and in a password manager. Some templates generate it for you
EmailAn SMTP server. Kaeso emails sign-in links, invitations and alerts
The first userKAESO_SETUP_EMAIL: the gateway emails the one-time setup link at every start until the first user exists, because the gateway image has no shell
Request logsAn external ClickHouse, such as ClickHouse Cloud, in KAESO_CLICKHOUSE_URL. Without it, request logs are off, and usage, limits and budgets work the same
A public addressKAESO_PUBLIC_URL, the https address people and apps use

Kaeso encrypts provider keys with the master key, so a database backup can't be read without it. Keep a copy outside the platform.

What was tested

Each guide says honestly which parts were deployed live and which were only checked. In short: the Render blueprint, the Railway button and file, and the quick servers on AWS and Google Cloud were deployed from empty accounts during the release candidates. The edge, the Coolify file and the Dokploy template ran locally with Docker. DigitalOcean's spec passed App Platform's validation, the Fly.io files the fly.toml schema, the Azure template Microsoft's template toolkit, and the managed stacks the linters in CI. The platforms page in the docs (opens in a new tab) keeps the full record.

If you deploy on a platform whose live test is still open, we would like to hear how it went: tell us, or open an issue on GitHub (opens in a new tab).

By Kaeso Team

On this page

Own the gateway.Own the record.

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