Skip to content

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
A bright gradient of orchid and pink, folding diagonally upward, with a warm light in one corner

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 get

  • 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

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.

Deploy

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:

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

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

The 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 back

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 know

  • 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 tested

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 steps

By Kaeso Team

On this page

Own the gateway.Own the record.

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