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

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 get01
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
| Service | Image | Reached by |
|---|---|---|
edge | The console image, running kaeso-edge | Everyone, through Coolify's proxy on your domain |
gateway | The gateway image | The edge |
console | The console image | The edge |
postgres, clickhouse, valkey | The releases the Compose package runs | 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.
Deploy02
- 01
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 - 02
Under the
edgeservice, set the domain tohttps://and your domain, such ashttps://kaeso.example.com, and point its DNS record at the server. Kaeso needs anhttpsaddress. - 03
Under Environment Variables, fill in your SMTP server, if you have one:
Variable What to enter KAESO_MAIL_TRANSPORTsmtpto send email;log, the default, only logs the kind of each emailKAESO_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 - 04
Deploy, and wait until every service is healthy.
- 05
Copy
SERVICE_REALBASE64_32_MASTERKEYfrom Environment Variables into a password manager. The master key isk1:followed by that value. Kaeso encrypts provider keys with it, so a backup of the database can't be read without it. - 06
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 back03
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 know04
- 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 tested05
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 steps06
- Backups and master keys (opens in a new tab): back up the volumes on your server.
- Where to run Kaeso: how Coolify compares with the other platforms.
By Kaeso Team


