Deploy Kaeso on Fly.io
Run Kaeso on Fly.io as four apps on the private network, an edge, a gateway, a console and Valkey, with Fly Managed Postgres. Every command, from creating the apps to your own certificate.
- Published
- Reading time
- 3 min
- Author
- Kaeso Team

Fly.io runs one app per fly.toml, and Kaeso needs four. deploy/fly/ in the repository holds a Fly Launch configuration for each, pinned to one release, and Fly Managed Postgres holds the database. Fly has no deploy button for a project of several apps, so this guide is a handful of fly commands.
What you get01
…-edge- File
edge.toml- Image
- The console image, running
kaeso-edge - Machine
shared-cpu-1x, 256 MB
…-gateway- File
gateway.toml- Image
- The gateway image
- Machine
shared-cpu-2x, 2 GB
…-console- File
console.toml- Image
- The console image
- Machine
shared-cpu-1x, 256 MB
…-valkey- File
valkey.toml- Image
- Valkey, on a 1 GB volume
- Machine
shared-cpu-1x, 512 MB
| App | File | Image | Machine |
|---|---|---|---|
…-edge | edge.toml | The console image, running kaeso-edge | shared-cpu-1x, 256 MB |
…-gateway | gateway.toml | The gateway image | shared-cpu-2x, 2 GB |
…-console | console.toml | The console image | shared-cpu-1x, 256 MB |
…-valkey | valkey.toml | Valkey, on a 1 GB volume | shared-cpu-1x, 512 MB |
Only the edge has a public service. The others are reachable only at <app>.internal on your organization's private network, which is IPv6, so the gateway listens on [::]:8080. The edge reads Fly-Client-IP, which Fly's proxy sets, rather than the caller-controlled X-Forwarded-For.
Valkey keeps its data within 256 MB and never evicts a key, so a full Valkey refuses writes instead of dropping limit counters. It runs on one machine with one volume, which Fly doesn't replicate. That is acceptable for what it holds: the gateway rebuilds budget counters from PostgreSQL, and rate windows start over.
Deploy02
1. Generate a master key into a variable, and copy what echo prints into a password manager:
export KAESO_MASTER_KEYS=$(docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate)echo $KAESO_MASTER_KEYS2. Sign in and clone the branch prod, which holds the latest release:
fly auth logingit clone --branch prod https://github.com/logicplanes/kaeso.gitcd kaeso3. Create the four apps. App names are unique across Fly.io, so choose a prefix of your own:
export KAESO_APP=kaeso-examplefly apps create $KAESO_APP-edgefly apps create $KAESO_APP-gatewayfly apps create $KAESO_APP-consolefly apps create $KAESO_APP-valkey4. Create the database in the apps' region, and attach it to the gateway. fly mpg list shows the cluster's id:
fly mpg create --name $KAESO_APP --region fra --pg-major-version 17fly mpg attach $CLUSTER_ID --app $KAESO_APP-gateway --variable-name KAESO_POSTGRES_URL5. Set the secrets, with your SMTP server in place of the examples:
export VALKEY_PASSWORD=$(openssl rand -hex 24)fly secrets set --stage --app $KAESO_APP-valkey VALKEY_PASSWORD=$VALKEY_PASSWORDfly secrets set --stage --app $KAESO_APP-edge \ KAESO_GATEWAY_UPSTREAM=$KAESO_APP-gateway.internal:8080 \ KAESO_CONSOLE_UPSTREAM=$KAESO_APP-console.internal:3000fly secrets set --stage --app $KAESO_APP-gateway \ KAESO_PUBLIC_URL=https://$KAESO_APP-edge.fly.dev \ KAESO_VALKEY_URL=redis://:$VALKEY_PASSWORD@$KAESO_APP-valkey.internal:6379 \ KAESO_MASTER_KEYS="$KAESO_MASTER_KEYS" \ KAESO_SETUP_EMAIL=owner@example.com KAESO_SMTP_HOST=smtp.example.com KAESO_SMTP_USER=kaeso \ KAESO_SMTP_PASSWORD=secret KAESO_SMTP_FROM="Kaeso <kaeso@example.com>"6. Deploy Valkey and the console as one machine each, then the gateway and the edge:
fly deploy --config deploy/fly/valkey.toml --app $KAESO_APP-valkey --ha=falsefly deploy --config deploy/fly/console.toml --app $KAESO_APP-console --ha=falsefly deploy --config deploy/fly/gateway.toml --app $KAESO_APP-gatewayfly deploy --config deploy/fly/edge.toml --app $KAESO_APP-edge7. Create the first user from the one-time setup link the gateway emails to KAESO_SETUP_EMAIL. The gateway image has no shell, so if the email doesn't arrive, read the SMTP error in the gateway's logs, correct the secrets, and the gateway sends a new link at its next start.
For request logs, set KAESO_CLICKHOUSE_URL on the gateway to a ClickHouse HTTP URL, such as ClickHouse Cloud. Without it, request logs are off, and usage, limits and budgets work the same.
Your own domain03
Add a certificate to the edge, point the DNS records where fly certs add says, and give the gateway the new address:
fly certs add kaeso.example.com --app $KAESO_APP-edgefly secrets set --app $KAESO_APP-gateway KAESO_PUBLIC_URL=https://kaeso.example.comUpdate and roll back04
A release changes the image tags in edge.toml, gateway.toml and console.toml. Pull prod, and deploy the gateway, then the console and the edge, with the commands of step 6. The gateway migrates the database at start, forward only, and a machine gets 75 seconds to drain when it stops. To roll back, deploy an earlier image:
fly deploy --config deploy/fly/gateway.toml --app $KAESO_APP-gateway \ --image ghcr.io/logicplanes/kaeso-gateway:0.6.0Good to know05
- Fly Machines have no read-only root file system and no setting to drop Linux capabilities, so the apps run with the images' users only.
- Managed Postgres offers PostgreSQL 16 and 17, where the Compose package runs 18. Kaeso runs on 17, as on Google Cloud.
- The gateway trusts every address of the organization's private network. Run Kaeso in an organization of its own when other apps there shouldn't be able to set the client address the gateway logs.
What was tested06
The files pass the SchemaStore schema for fly.toml, and the edge's routing, streaming and client-address handling pass the local edge tests. Kaeso hasn't been deployed on Fly.io from an empty account yet. If you do, tell us how it went.
Next steps07
- Fly.io in the docs (opens in a new tab), with the files explained.
- Backups and master keys (opens in a new tab): back up Managed Postgres and keep the master key outside Fly.io.
- Where to run Kaeso: how Fly.io compares with the other platforms.
By Kaeso Team


