Kubernetes operator for Stoat self-hosted instances, modeled on the upstream stoatchat/self-hosted Docker Compose stack.
Declare a Stoat custom resource; the operator reconciles secrets/config, optional embedded dependencies (MongoDB, Valkey, RabbitMQ, MinIO/Silo), Stoat app services, an in-cluster Caddy edge, Ingress, and LiveKit (hostNetwork for RTC).
Operator image: harbor.dataknife.net/library/stoat-operator
Clients → Ingress (TLS) → Caddy
↓
/api /ws /autumn /january /gifbox /livekit /ingress → app Services
↓
MongoDB · Valkey · RabbitMQ · S3/Silo
Voice RTC → LiveKit hostNetwork (7881/tcp + 50000–50100/udp on the node)
Admin (optional) → Ingress host (e.g. stoat-admin.*) → admin-panel:3000
→ Authentik SSO · MongoDB · Redis
Compose-compatible Service names (database, api, redis, …) are used so Stoat defaults resolve. One Stoat CR per namespace is recommended.
| API group | stoat.dataknife.ai |
| Kind | Stoat (shortName st) |
| Version | v1alpha1 |
Notable spec fields: domain, version, generateSecrets / secretsRef, dependencies (embed vs external), ingress, livekit, gifbox, admin, scaling, storage.
Set spec.scaling.replicas: 2 (or per-component overrides) to run multiple pods for
api, events, autumn, january, gifbox, web, caddy, pushd, and admin-panel. Rolling
updates + preferred pod anti-affinity apply when replicas > 1. Crond, LiveKit,
voice-ingress, and embedded Mongo/Redis/Rabbit/MinIO stay singleton — point
dependencies at external managed services for data-plane HA.
Two options:
- Embedded MinIO/Silo (default) — omit
dependencies.objectStorage; the operator deploys MinIO and creates bucketrevolt-uploads(path-style S3). - External S3 (e.g. RustFS) — set
dependencies.objectStoragewithendpoint,credentialsSecret(keysaccessKeyId/secretAccessKey), and optionalbucket/region/pathStyleBuckets. Seeconfig/samples/stoat_rustfs.yaml.
Optional DataKnifeAI/stoat-admin (Authentik + Mongo), off by default. Replaces the upstream WIP service-admin-panel.
- Build/push image:
docker build -t harbor.dataknife.net/library/stoat-admin-panel:latest -f deploy/admin-panel/Dockerfile deploy/admin-panel && docker push … - Create an Authentik OAuth2/OIDC provider for the admin host. Redirect URI:
https://<admin.domain>/api/auth/callback/authentik - Create Secret (see
.env.admin.example):
kubectl -n stoat create secret generic stoat-admin-sso \
--from-literal=authentikId=… \
--from-literal=authentikSecret=… \
--from-literal=authentikIssuer=https://auth.dataknife.net/application/o/<slug> \
--from-literal=nextAuthSecret="$(openssl rand -base64 32)"Authentik’s discovery issuer ends with /. The admin app normalizes either form; the operator still trims when writing env.
- Set
spec.admin(enabled,domain,credentialsSecret,platformAccountId= your Stoat user ULID). Operator creates Deployment/Service Ingressstoat-adminpointing atadmin-panel:3000(not via Stoat Caddy).
kubectl create namespace stoat
kubectl apply -k config/default
kubectl apply -f config/samples/stoat_v1alpha1_stoat.yaml
kubectl get stoat -n stoat
kubectl get deploy,svc,ingress -n stoatPoint DNS for spec.domain at your Ingress. Set spec.ingress.tlsSecretName (or Ingress annotations) for HTTPS.
Site-local (LAN/VPN) is the default (livekit.useExternalIP: false). That means
clients on your local network — not the Kubernetes pod network — reach LiveKit
via hostNetwork on the node LAN IP (or a kube-vip). Set livekit.address plus
livekit.serviceType: LoadBalancer for a stable VIP covering 7881/tcp and the
UDP media range. Signaling still goes through Ingress/Caddy on your domain.
With generateSecrets: true (default), the operator creates Secret stoat-secrets once and does not rotate keys. Losing REVOLT__FILES__ENCRYPTION_KEY permanently locks stored files — back up the Secret.
Bring-your-own: set secretsRef to an existing Secret with the upstream secrets.env keys.
make generate manifests
make test
make buildRequires Go 1.25+, controller-gen, and optionally golangci-lint.
| Area | State |
|---|---|
| Project scaffold (kubebuilder v4) | Done |
Stoat CRD + sample |
Done |
| Secret generation (VAPID, files, LiveKit) | Done |
| Revolt.toml / livekit.yml / Caddy / web env | Done |
| Embedded Mongo / Valkey / Rabbit / MinIO + bucket Job | Done |
| App Deployments + Services | Done |
| Caddy edge + Ingress | Done |
| LiveKit (hostNetwork RTC) | Done |
| External dependency refs (partial URI wiring) | Partial |
| Upgrades from self-hosted notices | Planned |
App-tier HA (spec.scaling.replicas) |
Done |
| HA embedded Mongo/Redis/Rabbit | External deps recommended |
