Skip to content

Deploy Kaeso on DigitalOcean

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.

Published
Reading time
3 min
Author
Kaeso Team
A bright gradient of orange and peach, folding diagonally downward, with a warm light in one corner

DigitalOcean's App Platform runs containers behind an edge that terminates TLS and routes by path. Kaeso uses that edge directly: the app sends the APIs to the gateway and everything else to the console, so no kaeso-edge runs here.

The repository has two app specs. .do/deploy.template.yaml is what the Deploy to DigitalOcean button reads, with Valkey running inside the app. .do/app.yaml uses a managed Valkey database instead, and you create it with doctl. Use the button to try Kaeso, and doctl for an install you keep.

What you get

  • kaeso-gateway
    Kind
    Service on port 8080, the gateway image
    Size
    apps-s-1vcpu-2gb
  • kaeso-console
    Kind
    Service on port 3000, the console image
    Size
    apps-s-1vcpu-0.5gb
  • kaeso-postgres
    Kind
    Dev database, PostgreSQL 18
    Size
    512 MB
  • kaeso-valkey (button)
    Kind
    Service on port 6379, for the app's own components only
    Size
    apps-s-1vcpu-0.5gb
  • kaeso-valkey (doctl)
    Kind
    Managed Valkey database, created first
    Size
    Your choice

The edge routes /v1, /v1beta, /v2, /platform, /mcp, /oauth and /.well-known to the gateway, and every other path to the console. The gateway trusts X-Forwarded-For from the private network, where the edge sits, and keeps its metrics on its loopback address.

KAESO_PUBLIC_URL is ${APP_URL}, the app's primary address, and the database addresses come from the databases, so you type none of them.

The values to fill

ValueWhat to enter
KAESO_MASTER_KEYSA master key, also kept in a password manager
KAESO_SETUP_EMAILYour address; the gateway emails the setup link there
KAESO_SMTP_HOST, KAESO_SMTP_USER, KAESO_SMTP_PASSWORD, KAESO_SMTP_FROMYour SMTP server
KAESO_CLICKHOUSE_URLA ClickHouse HTTP URL with user and password for request logs, or empty

Generate the master key with Docker:

docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate

App Platform encrypts a SECRET value when it first receives it.

Deploy with the button

  1. Open Deploy to DigitalOcean (opens in a new tab). App Platform reads the spec from the branch prod, which holds the latest release.
  2. In the environment variables of kaeso-gateway, fill in the values above, and choose another region if you like.
  3. Create the app, and wait until its first deployment is live.
  4. Open the one-time setup link the gateway emailed you, and create the first user.

The button can create dev databases only, and those exist only for PostgreSQL. So its Valkey runs as a service in the app, keeps its data within 256 MB and never evicts a key. It starts empty at each of its deployments, which is fine for what it holds: the gateway rebuilds budget counters from PostgreSQL, and rate windows start over. The dev database keeps no backups, though, so for production use doctl, or move the app to a managed PostgreSQL cluster and a managed Valkey.

Deploy with doctl

Install doctl (opens in a new tab), sign in, and create the Valkey database in the app's region:

doctl auth initdoctl databases create kaeso-valkey --engine valkey --region fra1 --size db-s-1vcpu-1gb --num-nodes 1 --wait

In the database's Settings, set Eviction policy to No eviction, so a full database refuses writes instead of dropping limit counters. Then copy .do/app.yaml from the release you deploy, fill in the values, and create the app:

doctl apps create --spec app.yaml --wait

The managed Valkey speaks TLS with a certificate of DigitalOcean's own authority, which the spec hands to the gateway as KAESO_VALKEY_CA. For a database with backups, create a managed PostgreSQL cluster and point kaeso-postgres at it with production: true and its cluster_name.

Your own domain

From the button: add the domain in the app's Settings under Domains, and point the DNS record where App Platform says. ${APP_URL} follows the primary domain, so the gateway redeploys with the new address.

From doctl: add it under domains in the spec with type: PRIMARY, apply the spec with doctl apps update, and point the DNS record where the app's Networking tab says.

Update and roll back

A release changes the image tags of kaeso-gateway and kaeso-console. Set both tags in your app's spec and apply it:

doctl apps spec get $APP_ID > app.yamldoctl apps update $APP_ID --spec app.yaml --wait

The gateway migrates the databases at start, forward only. To roll back, choose Rollback beside an earlier deployment on the app's Activity tab; App Platform keeps the ten most recent successful deployments.

What was tested

App Platform's validation and proposal API accepted the button's spec on 2026-11-09. Kaeso hasn't been deployed on DigitalOcean from an empty account yet. If you do, tell us how it went.

Next steps

By Kaeso Team

On this page

Own the gateway.Own the record.

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