Deploy Kaeso on Dokploy
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.
- Published
- Reading time
- 3 min
- Author
- Kaeso Team

Dokploy (opens in a new tab) imports templates as a Compose file and a configuration together. deploy/dokploy/ in the Kaeso repository holds both, docker-compose.yml and template.toml, in the format of Dokploy's own template collection. They run a public edge behind Dokploy's Traefik, a private gateway and console, and the Compose package's PostgreSQL, ClickHouse and Valkey on your server, all pinned to one release.
What you get01
edge- Image
- The console image, running
kaeso-edge - Reached by
- Everyone, through Traefik on the template's 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 Traefik on the template's 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.
template.toml gives the edge a domain on port 8080 and sets the environment: random passwords from Dokploy's hash helper, and a master key of 32 random bytes from its base64 helper. Email is only logged until you add an SMTP server.
Deploy02
1. Make the import text. On a computer with curl and jq, turn the template of the branch prod, which holds the latest release, into the Base64 text Dokploy imports:
curl -fsSLO https://raw.githubusercontent.com/logicplanes/kaeso/prod/deploy/dokploy/docker-compose.ymlcurl -fsSLO https://raw.githubusercontent.com/logicplanes/kaeso/prod/deploy/dokploy/template.tomljq -n --rawfile compose docker-compose.yml --rawfile config template.toml \ '{compose: $compose, config: $config}' | base64 | tr -d '\n'2. Import it. In Dokploy, open a project and create a Compose service. Under Advanced, paste the text into Import. Dokploy shows the Compose file, the environment, the mounts and the domain before it applies them.
3. Set the domain. Under Domains, change the host to your domain, such as kaeso.example.com, turn on HTTPS with Let's Encrypt, and point the domain's DNS record at the server.
4. Fill in the environment. Under Environment, set KAESO_PUBLIC_URL to https:// and that domain, and add 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 |
5. Deploy, and wait until every service is healthy.
6. Keep the master key. Copy KAESO_MASTER_KEYS from Environment into a password manager. Kaeso encrypts provider keys with it, so a backup of the database can't be read without it.
7. Create the first user from the setup link. With SMTP, it arrives at KAESO_SETUP_EMAIL. Without, print it on the server, with the service's app name from its General tab in place of kaeso-example:
docker exec kaeso-example-gateway-1 kaeso setup-linkThe gateway image has no shell, so Dokploy's terminal for the gateway's container can't run the command; use the server's.
Update and roll back03
A release changes the image tags in docker-compose.yml. Open the service's Compose file in Dokploy, set the tags of edge, gateway and console to the new release, and deploy; the environment stays. 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 Dokploy.
- Traefik terminates TLS. The gateway writes a keepalive into every stream, so long streams outlast the proxy's idle timeout.
What was tested05
The template's Compose file ran locally with Docker on 2026-11-09, with healthy services, path routing and the setup link. It hasn't been imported on a Dokploy 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 Dokploy compares with the other platforms.
By Kaeso Team


