Skip to content

About

Kubernetes operator for Stoat self-hosted chat instances (umbrella CR for the stoatchat/self-hosted stack)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Stoat Operator

Stoat Kubernetes operator

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

Architecture

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.

CRD

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.

App-tier HA

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.

Object storage

Two options:

  1. Embedded MinIO/Silo (default) — omit dependencies.objectStorage; the operator deploys MinIO and creates bucket revolt-uploads (path-style S3).
  2. External S3 (e.g. RustFS) — set dependencies.objectStorage with endpoint, credentialsSecret (keys accessKeyId / secretAccessKey), and optional bucket / region / pathStyleBuckets. See config/samples/stoat_rustfs.yaml.

Admin panel

Optional DataKnifeAI/stoat-admin (Authentik + Mongo), off by default. Replaces the upstream WIP service-admin-panel.

  1. Build/push image: docker build -t harbor.dataknife.net/library/stoat-admin-panel:latest -f deploy/admin-panel/Dockerfile deploy/admin-panel && docker push …
  2. Create an Authentik OAuth2/OIDC provider for the admin host. Redirect URI: https://<admin.domain>/api/auth/callback/authentik
  3. 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.

  1. Set spec.admin (enabled, domain, credentialsSecret, platformAccountId = your Stoat user ULID). Operator creates Deployment/Service Ingress stoat-admin pointing at admin-panel:3000 (not via Stoat Caddy).

Quick start

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 stoat

Point 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.

Secrets

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.

Development

make generate manifests
make test
make build

Requires Go 1.25+, controller-gen, and optionally golangci-lint.

Status

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

References

About

Kubernetes operator for Stoat self-hosted chat instances (umbrella CR for the stoatchat/self-hosted stack)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages