Self-hosting
Deploy
Section titled “Deploy”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).
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:docker compose up -d # pulls the right architecture automaticallyPublishing images
Section titled “Publishing images”.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 |
git tag v0.1.0 -m "Kinglet v0.1.0"git push origin v0.1.0Configuration
Section titled “Configuration”| 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) |
Sizing
Section titled “Sizing”- 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.
Backups
Section titled “Backups”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/kingletTLS and upgrades
Section titled “TLS and upgrades”- 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_URLto the public HTTPS origin so session cookies areSecureand alert links are correct. - Upgrades:
docker compose pull && docker compose up -d. Graceful shutdown flushes SQLite onSIGTERM, sodocker compose stopis safe.