Komodo CD

Redeploy your Komodo stacks from CI.

Komodo CD is a small self-hosted dashboard on top of Komodo: the state of every stack, one-click Pull or Redeploy, and a ready-to-paste curl so your pipeline does the same after every push.

Install on a server
curl -fsSL https://raw.githubusercontent.com/Nonetss/Komodo-CD/main/scripts/bootstrap.sh | bash

Run it in an empty directory. It asks a few questions, generates the secret and starts the stack with Docker Compose.

Read the docsSource on GitHub
komodo-cd.example.com/

What you get

  1. Every stack, one page each.

    The stacks list stays on the left, with search and filters for running, stopped or with issues. Open one to see its services and images, which of them has a new image, the deployed commit against the latest one, the three actions and the curl that runs each of them from CI. Tick several to run the same action on all of them.

    komodo-cd.example.com/stacks/photos

  2. Pull, redeploy, or both.

    Pick a stack and an action. Pull updates the images without restarting, Redeploy brings the whole stack down and up again, Pull + Redeploy does both. Under the form, the same action as a curl ready for a GitHub or Gitea Actions workflow.

    komodo-cd.example.com/deploy

  3. Every deploy leaves a trace.

    Actions launched from the dashboard and from CI land in the same history, with who ran them (a user or the name of the API key), the result and Komodo's own error message when one fails.

    komodo-cd.example.com/history

  4. Know what each image carries.

    Every image used by a stack is scanned with Trivy when it first shows up, after every deploy and on demand. The Security page sorts them by severity, says which vulnerabilities have a fix and which stacks use each image, and copies an image's report as Markdown. Private images it cannot pull are flagged as no access.

    komodo-cd.example.com/security

  5. One Komodo, one key pair.

    Paste the URL of your Komodo instance and a key and secret from its Settings → API Keys. They stay on the backend: the API lists the connection by name and URL, never with its credentials.

    komodo-cd.example.com/credentials

  6. Light or dark, English or Spanish.

    Both themes and both languages are built in and remembered per browser. On a phone the top navigation becomes a bottom bar, so a redeploy is a couple of taps away.

    komodo-cd.example.com/stacks/photos

And the rest

Status at a glance
The overview gathers the key figures: stacks by state, what needs attention or has something new to deploy, image vulnerabilities and the deploys of the last 30 days with their success rate.
Update hints
A stack is flagged when one of its images has an update or the deployed commit is behind the latest one, and a single Pull + Redeploy from the Stacks page brings the selected ones up to date.
API keys
Personal keys sent as x-api-key, shown once when created. Each pipeline can have its own and be revoked alone.
OpenAPI reference
Every endpoint is documented in an interactive reference at /scalar, with the spec at /doc.
Failure alerts
Optional ntfy notifications, on ntfy.sh or your own server, whenever a deploy fails, from CI or by hand.
Four containers, no database server
Backend, frontend and gateway on ghcr.io, tagged latest and by release, plus the official Trivy server for the scans. SQLite in a single volume: no database server to run.

How it fits together

Four containers run with Docker Compose. The gateway runs Caddy, the only published port, which sends the API to the backend and every page to Astro SSR in the frontend container. The backend owns a SQLite file, talks to your Komodo instance and sends the images to scan to a Trivy server, and Komodo does the actual deploy on your servers.

Request paths

Opening a page
  1. Browser
    → HTTPS
  2. Caddy:80
    Gateway
    → /*
  3. Astro SSR:4321
    Frontend · React
    → /api/auth
  4. Backend:3000
    Better Auth
Deploying from CI
  1. CI runner
    GitHub · Gitea
    → POST /api/v0/deploy
  2. Caddy:80
    Gateway
    → /api
  3. Backend:3000
    Hono · oRPC
    SQLite · db_data
    → HTTPS
  4. Komodo
    Core API
    → PullStack · DeployStack
  5. Your servers
    Komodo Periphery

Gateway routing

RequestGoes to
/rpc/* /api/*backend:3000
/doc /scalarbackend:3000
any other pathfrontend:4321

Only the gateway's port 80 is mapped to the host, as PORT. The backend and the frontend are reachable only inside the Compose network. Caddy also answers /health and adds basic security headers to every response.

The Komodo secret stays on the backend.
The key and secret are stored in the backend's database and used only to call Komodo. Listing the connection returns its name and URL, never the credentials.
One door for people and pipelines.
The same endpoints take a session cookie from the browser or an x-api-key header from CI. Both end up in the history, a key under its own name.
Komodo stays the source of truth.
Stacks are read from Komodo on every request and actions call its PullStack and DeployStack. Komodo CD only stores users, API keys, the connection, the ntfy settings and the history.
Read the architecture docs

Up in one command.

On a Linux host with Docker, curl and openssl, from an empty directory:

curl -fsSL https://raw.githubusercontent.com/Nonetss/Komodo-CD/main/scripts/bootstrap.sh | bash

Everything Komodo CD stores lives in the db_data volume: users, API keys, the Komodo connection, the ntfy settings and the history. Back it up, and keep in mind that docker compose down -v deletes it.

Prefer to set it up by hand? Deploy with Docker Compose

What the script does

  1. 1Asks for the host port, the public URL and the first admin's name, email and password.
  2. 2Generates BETTER_AUTH_SECRET with openssl and writes .env with mode 600. An existing .env is never overwritten.
  3. 3Downloads compose.yml into the current directory.
  4. 4Optionally pulls the images from ghcr.io and starts the stack. The backend migrates the database and creates the admin on startup.
komodo-cd.example.com