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

# Deploy Kaeso on AWS

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.

> 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

`deploy/aws/` in the Kaeso repository holds two CloudFormation templates for two different needs. The **quick server** is the Compose package on one EC2 instance, exactly as on your own server, and launches in one click. The **managed stack** runs Kaeso on ECS Fargate with AWS's own data stores, for installs that outgrow one machine.

Every release uploads both templates to `https://kaeso-cloudformation.s3.amazonaws.com/vX.Y.Z/`, and a stable release also to `latest/`.

## The quick server

[Launch on AWS](https://console.aws.amazon.com/cloudformation/home#/stacks/create/review?templateURL=https%3A%2F%2Fkaeso-cloudformation.s3.amazonaws.com%2Flatest%2Fquick-server.yaml&stackName=kaeso) opens the published template in CloudFormation. It creates:

- one Graviton instance with Ubuntu 24.04, `t4g.medium` with a 40 GB disk by default;
- an Elastic IP, and a security group for HTTP, HTTPS and HTTP/3, with SSH only from an address range you choose;
- an optional Route 53 record for your domain.

At first boot, the instance runs Kaeso's installer. It installs Docker, writes the settings, generates the master key and starts the Compose package with Caddy, a bundled ClickHouse for request logs, and the updater. So **Update** in the console works, as on any Compose install.

From the CLI, with a clone of the repository:

```bash
aws cloudformation deploy --stack-name kaeso --template-file deploy/aws/quick-server.yaml \
  --parameter-overrides Domain=kaeso.example.com KeyName=my-key \
  AllowedSshCidr=203.0.113.0/24 HostedZoneId=Z0123456789
```

| Parameter | What it is |
| --- | --- |
| `Domain` | The domain Kaeso answers on; without `HostedZoneId`, point its A record at the `PublicIp` output |
| `KaesoVersion` | A release to install; empty installs the newest stable release |
| `InstanceType`, `DiskSizeGb` | `t4g.medium` and 40 GB by default |
| `KeyName`, `AllowedSshCidr` | SSH access, which `kaeso setup-link` needs |
| `HostedZoneId` | A Route 53 zone of the domain, to create its record |

Once the stack is complete and Caddy has its certificate, run the `SetupLink` output over SSH. It prints the one-time link that creates the first user.

## The managed stack

`deploy/aws/managed.yaml` builds Kaeso from AWS services:

- a VPC with two public and two private subnets and one NAT gateway;
- an Application Load Balancer with your ACM certificate, HTTP redirected to HTTPS, path rules that send the APIs, the MCP server and its sign-in to the gateway and everything else to the console, and an idle timeout of 300 seconds for long streams;
- an ECS cluster on Fargate with Graviton, in the private subnets: a gateway service of 2 tasks with 2 vCPUs and 4 GB each by default, and a console service;
- RDS PostgreSQL 18, and ElastiCache Valkey with `noeviction`, TLS and an AUTH token, both reachable only from the gateway;
- Secrets Manager secrets for the master keys, the database password, the Valkey token, the SMTP password and the ClickHouse URL;
- CloudWatch log groups, and an optional Route 53 alias.

```bash
aws cloudformation deploy --stack-name kaeso --template-file deploy/aws/managed.yaml \
  --capabilities CAPABILITY_IAM --parameter-overrides \
  Domain=kaeso.example.com \
  CertificateArn=arn:aws:acm:eu-central-1:123456789012:certificate/example \
  MasterKeys="$(docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate)" \
  SetupEmail=owner@example.com SmtpHost=smtp.example.com SmtpUser=kaeso \
  SmtpPassword=secret SmtpFrom="Kaeso <kaeso@example.com>"
```

Keep a copy of the master key in a password manager too: Kaeso encrypts provider keys with it. Other parameters size the stack: `GatewayCpu`, `GatewayMemory` and `GatewayCount` for the gateway, and `DatabaseInstanceClass`, `DatabaseStorageGb` and `CacheNodeType` for the data stores. Several gateway tasks share limits, caches and route cooldowns through Valkey. For request logs, set `ClickHouseUrl` to a ClickHouse such as ClickHouse Cloud; empty keeps them off.

The gateway emails the one-time setup link to `SetupEmail` until the first user exists. It trusts `X-Forwarded-For` only from the VPC, where the load balancer's nodes sit. The load balancer checks `/readyz` on the gateway and `/healthz` on the console, and a gateway task gets 75 seconds to drain when it stops.

## Update and roll back

On the quick server, update from the console, automatically in a window you choose, or by hand, as on any Compose install. Deploying the template again doesn't update Kaeso.

On the managed stack, a release changes the image tags in `managed.yaml`. Deploy the new template over the stack: ECS replaces the tasks with a circuit breaker that rolls back on failure, and the gateway migrates the databases at start, forward only. To roll back on purpose, deploy the previous release's template.

## What was tested

On 2026-11-07 the quick server was launched as a CloudFormation stack in `us-east-1` from an empty account, with the eighth release candidate. It created its first user and passed the checks for routing, streaming and logging after the master key file was put back under the installer's ownership on the test instance. The template now leaves that ownership alone, but the corrected template hasn't been redeployed from an empty account. The managed stack is linted and formatted in CI, and hasn't been deployed yet.

## Next steps

- [AWS in the docs](https://docs.kaeso.app/self-hosting/platforms/aws), with every parameter.
- [Scaling](https://docs.kaeso.app/self-hosting/scaling): what one, two and three gateways serve.
- [Where to run Kaeso](https://kaeso.app/articles/where-to-run-kaeso): how AWS compares with the other platforms.

By Kaeso Team

## More articles

- [Deploy Kaeso on Fly.io](https://kaeso.app/articles/deploy-kaeso-on-fly-io.md): 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.
- [Deploy Kaeso on Azure](https://kaeso.app/articles/deploy-kaeso-on-azure.md): Run Kaeso on one Azure virtual machine from the Deploy to Azure button or the Azure CLI. The installer runs at first boot, and the setup link comes through Cloud Shell without SSH.

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