Skip to content

Self-hosting

Kinglet ships as a multi-arch image (linux/amd64 + linux/arm64) at ghcr.io/rushlightlab/kinglet — the repo’s release workflow publishes it (see Publishing images).

docker-compose.yml
services:
kinglet:
image: ghcr.io/rushlightlab/kinglet:latest # pin a version in production, e.g. :0.1.0
ports:
- "8080:3000"
environment:
KINGLET_DB_PATH: /data/kinglet.db
KINGLET_RETENTION_DAYS: 14
volumes:
- kinglet-data:/data
restart: unless-stopped
volumes:
kinglet-data:
Terminal window
docker compose up -d # pulls the right architecture automatically

.github/workflows/docker.yml builds and pushes the image:

Trigger Tags
push to main :latest, :main, :sha-<commit>
push tag vX.Y.Z :X.Y.Z, :X.Y, :latest
Terminal window
git tag v0.1.0 -m "Kinglet v0.1.0"
git push origin v0.1.0
Env var Default What it does
KINGLET_PORT 3000 HTTP port inside the container
KINGLET_STORAGE auto sqlite, libsql, or auto (picks by db path scheme)
KINGLET_DB_PATH data/kinglet.db Plain path → SQLite; libsql:///https:///file: → libSQL
KINGLET_DB_AUTH_TOKEN — Auth token for remote libSQL/Turso
KINGLET_ADMIN_EMAIL admin@kinglet.local Bootstrap administrator email (first boot only)
KINGLET_ADMIN_PASSWORD (generated) Bootstrap administrator password (first boot only)
BETTER_AUTH_SECRET (generated, persisted) Session signing secret — set explicitly for multi-instance installs
KINGLET_TRUSTED_PROXIES — CIDRs allowed to set X-Forwarded-For
KINGLET_ALLOW_PRIVATE_WEBHOOKS — Allow private/internal webhook targets (SSRF escape hatch)
KINGLET_DISABLE_LEGACY_TOKENS — Disable workspace-wide tok_… superuser tokens
KINGLET_SESSION_DAYS 30 Web session lifetime
KINGLET_TOKENS (auto-generate) Legacy global tokens — all projects, full access
KINGLET_RETENTION_DAYS 14 Delete events older than this
KINGLET_MAX_EVENTS_PER_PROJECT 1000000 Hard cap on retained events per project (0 = unlimited)
KINGLET_MAX_DB_MB 4096 Hard cap on local database size in MB (0 = unlimited)
  • RAM: ~150–250 MB steady state.
  • CPU: 2 vCPUs comfortably handle millions of events per day — ingest is batched SQLite writes, not per-request round trips.
  • Disk: roughly 300–500 MB per million retained events. With the default 14-day retention, a busy small app stays in single-digit gigabytes.

The whole store is one file. Litestream replicates it continuously to S3-compatible storage with a one-line sidecar:

litestream:
image: litestream/litestream
volumes:
- kinglet-data:/data
command: replicate /data/kinglet.db s3://your-bucket/kinglet
  • A ready-made Caddy setup lives in deploy/ (Caddyfile + docker-compose.tls.yml). It obtains certificates automatically, sets HSTS, and keeps Kinglet off the public network — only Caddy publishes 80/443.
  • Put Caddy or nginx in front for automatic TLS; the container speaks plain HTTP on its port. Set KINGLET_BASE_URL to the public HTTPS origin so session cookies are Secure and alert links are correct.
  • Upgrades: docker compose pull && docker compose up -d. Graceful shutdown flushes SQLite on SIGTERM, so docker compose stop is safe.