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

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

> 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

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 get

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

## Deploy

**1. Generate a master key** into a variable, and copy what `echo` prints into a password manager:

```bash
export KAESO_MASTER_KEYS=$(docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate)
echo $KAESO_MASTER_KEYS
```

**2. Sign in and clone** the branch `prod`, which holds the latest release:

```bash
fly auth login
git clone --branch prod https://github.com/logicplanes/kaeso.git
cd kaeso
```

**3. Create the four apps.** App names are unique across Fly.io, so choose a prefix of your own:

```bash
export KAESO_APP=kaeso-example
fly apps create $KAESO_APP-edge
fly apps create $KAESO_APP-gateway
fly apps create $KAESO_APP-console
fly apps create $KAESO_APP-valkey
```

**4. Create the database** in the apps' region, and attach it to the gateway. `fly mpg list` shows the cluster's id:

```bash
fly mpg create --name $KAESO_APP --region fra --pg-major-version 17
fly mpg attach $CLUSTER_ID --app $KAESO_APP-gateway --variable-name KAESO_POSTGRES_URL
```

**5. Set the secrets**, with your SMTP server in place of the examples:

```bash
export VALKEY_PASSWORD=$(openssl rand -hex 24)
fly secrets set --stage --app $KAESO_APP-valkey VALKEY_PASSWORD=$VALKEY_PASSWORD
fly secrets set --stage --app $KAESO_APP-edge \
  KAESO_GATEWAY_UPSTREAM=$KAESO_APP-gateway.internal:8080 \
  KAESO_CONSOLE_UPSTREAM=$KAESO_APP-console.internal:3000
fly 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:

```bash
fly deploy --config deploy/fly/valkey.toml --app $KAESO_APP-valkey --ha=false
fly deploy --config deploy/fly/console.toml --app $KAESO_APP-console --ha=false
fly deploy --config deploy/fly/gateway.toml --app $KAESO_APP-gateway
fly deploy --config deploy/fly/edge.toml --app $KAESO_APP-edge
```

**7. 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 domain

Add a certificate to the edge, point the DNS records where `fly certs add` says, and give the gateway the new address:

```bash
fly certs add kaeso.example.com --app $KAESO_APP-edge
fly secrets set --app $KAESO_APP-gateway KAESO_PUBLIC_URL=https://kaeso.example.com
```

## Update and roll back

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:

```bash
fly deploy --config deploy/fly/gateway.toml --app $KAESO_APP-gateway \
  --image ghcr.io/logicplanes/kaeso-gateway:0.6.0
```

## Good to know

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

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](https://kaeso.app/contact) how it went.

## Next steps

- [Fly.io in the docs](https://docs.kaeso.app/self-hosting/platforms/fly), with the files explained.
- [Backups and master keys](https://docs.kaeso.app/self-hosting/backups): back up Managed Postgres and keep the master key outside Fly.io.
- [Where to run Kaeso](https://kaeso.app/articles/where-to-run-kaeso): how Fly.io compares with the other platforms.

By Kaeso Team

## More articles

- [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.
- [Deploy Kaeso on AWS](https://kaeso.app/articles/deploy-kaeso-on-aws.md): Two CloudFormation templates run Kaeso on AWS. The quick server puts the Compose package on one Graviton instance in one click; the managed stack runs it on ECS Fargate with an Application Load Balancer, RDS and ElastiCache.

[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)
