Skip to content

Deploy Kaeso on Coolify

Run Kaeso on your own Coolify server from one Compose file. Coolify generates every password and the master key, its proxy handles TLS, and PostgreSQL, ClickHouse and Valkey run beside Kaeso.

Published
Reading time
3 min
Author
Kaeso Team
A pale gradient of orange and yellow, in gentle level folds

If you already run Coolify (opens in a new tab) on a server of yours, Kaeso fits in as one more resource. deploy/coolify/compose.yaml in the repository is a Docker Compose file made for it: a public edge behind Coolify's proxy, a private gateway and console, and the same PostgreSQL, ClickHouse and Valkey the Compose package runs, all pinned to one release.

Unlike the cloud platforms, you need no external database or ClickHouse here: everything runs on your Coolify server, request logs included.

What you get

  • edge
    Image
    The console image, running kaeso-edge
    Reached by
    Everyone, through Coolify's proxy on your domain
  • gateway
    Image
    The gateway image
    Reached by
    The edge
  • console
    Image
    The console image
    Reached by
    The edge
  • postgres, clickhouse, valkey
    Image
    The releases the Compose package runs
    Reached by
    The gateway

Each service keeps the Compose package's hardening: no new privileges, every Linux capability dropped but the ones a data store needs, a read-only root file system for Kaeso's own services, and memory and process limits. The gateway signs in to PostgreSQL as kaeso, which owns its database but isn't a superuser. Valkey never evicts a key, so a full Valkey refuses writes instead of dropping limit counters.

Coolify fills in every value whose name starts with SERVICE_: SERVICE_URL_EDGE_8080 is the edge's address, the SERVICE_PASSWORD_… values are random passwords, and SERVICE_REALBASE64_32_MASTERKEY is 32 random bytes, the master key.

Deploy

  1. In Coolify, open a project and add a resource of the type Docker Compose Empty. Paste the file from the branch prod, which holds the latest release:

    https://raw.githubusercontent.com/logicplanes/kaeso/prod/deploy/coolify/compose.yaml
  2. Under the edge service, set the domain to https:// and your domain, such as https://kaeso.example.com, and point its DNS record at the server. Kaeso needs an https address.

  3. Under Environment Variables, fill in your SMTP server, if you have one:

    VariableWhat to enter
    KAESO_MAIL_TRANSPORTsmtp to send email; log, the default, only logs the kind of each email
    KAESO_SETUP_EMAILYour address; with SMTP, the gateway emails the setup link there
    KAESO_SMTP_HOST, KAESO_SMTP_PORT, KAESO_SMTP_TLS, KAESO_SMTP_USER, KAESO_SMTP_PASSWORD, KAESO_SMTP_FROMYour SMTP server
  4. Deploy, and wait until every service is healthy.

  5. Copy SERVICE_REALBASE64_32_MASTERKEY from Environment Variables into a password manager. The master key is k1: followed by that value. Kaeso encrypts provider keys with it, so a backup of the database can't be read without it.

  6. Open the setup link to create the first user. With SMTP, it arrives at KAESO_SETUP_EMAIL. Without, print it on the server, in a terminal or Coolify's terminal for the server:

    docker exec $(docker ps --quiet --filter name=gateway-) kaeso setup-link

The gateway image has no shell, so Coolify's terminal for the gateway's own container can't run the command; use the server's. On a server with several Kaeso resources, give docker exec the gateway container that docker ps lists for this one.

Update and roll back

A release changes the image tags in the Compose file. Open the resource's Compose file in Coolify, set the tags of edge, gateway and console to the new release, and deploy; Coolify keeps the generated values. The gateway migrates the databases at start, forward only. To roll back, set the earlier tags.

Good to know

  • Kaeso's updater doesn't run here, so the console can't update Kaeso. You deploy each release in Coolify, which keeps it in one place with your other apps.
  • Coolify's proxy terminates TLS. The gateway writes a keepalive into every stream, so long streams outlast the proxy's idle timeout.

What was tested

The file ran locally with Docker on 2026-11-09, with healthy services, path routing and the setup link. It hasn't been deployed on a Coolify server 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