Skip to content

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.

Published
Reading time
3 min
Author
Kaeso Team
A pale gradient of green and teal, folding diagonally upward

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 (opens in a new tab) 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:

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
ParameterWhat it is
DomainThe domain Kaeso answers on; without HostedZoneId, point its A record at the PublicIp output
KaesoVersionA release to install; empty installs the newest stable release
InstanceType, DiskSizeGbt4g.medium and 40 GB by default
KeyName, AllowedSshCidrSSH access, which kaeso setup-link needs
HostedZoneIdA 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.
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

By Kaeso Team

On this page

Own the gateway.Own the record.

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