Skip to content

Deploy Kaeso on CapRover

Run Kaeso on your own CapRover server as a one-click app from the template in the repository. Six apps, one public edge behind CapRover's nginx, and PostgreSQL, ClickHouse and Valkey beside Kaeso.

Published
Reading time
3 min
Author
Kaeso Team
A deep gradient of orange, pink and violet, in upright folds like a curtain, with a warm light in one corner

CapRover (opens in a new tab) installs apps from one-click templates, and you can paste one of your own. deploy/caprover/kaeso.yml in the Kaeso repository is such a template. It creates six apps on your CapRover server: a public edge behind CapRover's nginx, a private gateway and console, and the Compose package's PostgreSQL, ClickHouse and Valkey, all pinned to one release.

What you get

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

The names follow the app name you give, kaeso here. Only the edge is a web app; the others are reachable only on CapRover's overlay network. The gateway signs in to PostgreSQL as kaeso, which owns its database but isn't a superuser. Valkey keeps its data within 512 MB and never evicts a key.

CapRover's nginx appends to the caller's X-Forwarded-For, so the edge reads X-Real-IP, which nginx sets, and the gateway trusts only private addresses. The template turns on websocket support for the edge, which makes nginx speak HTTP/1.1 to it.

Deploy

  1. Generate a master key, and keep it in a password manager:

    docker run --rm ghcr.io/logicplanes/kaeso-gateway:0.6.0 master-key generate
  2. In CapRover, open Apps, then One-Click Apps/Databases, and choose >> TEMPLATE << at the end of the list.

  3. Paste the template from the branch prod, which holds the latest release:

    https://raw.githubusercontent.com/logicplanes/kaeso/prod/deploy/caprover/kaeso.yml
  4. Fill in the form:

    FieldWhat to enter
    App namekaeso, or a name of your own
    Public URLThe app's address under your root domain, which the form fills in, or your own domain
    Master keyThe key from step 1
    PasswordsRandom ones, which the form fills in
    Mail transportsmtp to send email; log, the default, only logs the kind of each email
    Setup email, SMTP host, port, user, password, senderYour SMTP server, if you have one
  5. Deploy, and wait until the apps are created. The gateway restarts until PostgreSQL and Valkey answer.

  6. Open the app kaeso, turn on HTTPS and Force HTTPS, and connect your domain if the public URL names one.

  7. Open the setup link to create the first user. With SMTP, it arrives at the setup email. Without, print it on the server:

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

Update and roll back

A release changes the image tags in kaeso.yml. In each of the apps kaeso-gateway, kaeso-console and kaeso, open Deployment and deploy by image name with the new tag, such as ghcr.io/logicplanes/kaeso-gateway:0.6.0, gateway first. The gateway migrates the databases at start, forward only. To roll back, deploy the earlier tag the same way.

Good to know

  • CapRover reads only some Compose fields from a one-click app. Health checks, dropped capabilities, a read-only root file system and memory limits don't reach the apps, so they run with the images' defaults. If you want the full hardening on your own server, the installer gives you that.
  • nginx waits 60 seconds for a reply by default. Streams send keepalives, but a request without streaming that takes longer gets 504. Raise proxy_read_timeout in the edge app's nginx configuration if you need more.
  • Kaeso's updater doesn't run here; you deploy each release in CapRover.

What was tested

The template parses and uses only fields CapRover reads. It hasn't been deployed on a CapRover 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