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

# 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.

> 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

If you already run [Coolify](https://coolify.io) 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

| 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.

## 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:

   ```text
   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:

   | Variable | What to enter |
   | --- | --- |
   | `KAESO_MAIL_TRANSPORT` | `smtp` to send email; `log`, the default, only logs the kind of each email |
   | `KAESO_SETUP_EMAIL` | Your 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_FROM` | Your 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:

   ```bash
   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](https://kaeso.app/contact) how it went.

## Next steps

- [Coolify in the docs](https://docs.kaeso.app/self-hosting/platforms/coolify).
- [Backups and master keys](https://docs.kaeso.app/self-hosting/backups): back up the volumes on your server.
- [Where to run Kaeso](https://kaeso.app/articles/where-to-run-kaeso): how Coolify compares with the other platforms.

By Kaeso Team

## More articles

- [Deploy Kaeso on Google Cloud](https://kaeso.app/articles/deploy-kaeso-on-google-cloud.md): Two Terraform configurations run Kaeso on Google Cloud. The quick server puts the Compose package on one Compute Engine instance from Cloud Shell; the managed configuration runs it on Cloud Run with a load balancer, Cloud SQL and Memorystore.
- [Deploy Kaeso on Dokploy](https://kaeso.app/articles/deploy-kaeso-on-dokploy.md): Run Kaeso on your own Dokploy server by importing its template. Traefik handles TLS, the template generates every password and the master key, and PostgreSQL, ClickHouse and Valkey run beside Kaeso.

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