Kubernetes / Helm

Klaxon ships a Helm chart in deploy/helm/klaxon/ for production Kubernetes deployments.

Install

helm install klaxon deploy/helm/klaxon/ \
  --set secrets.databaseUrl="postgres://user:pass@db:5432/klaxon" \
  --set secrets.fcmServerKey="your-key" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=klaxon.sh

Components

The chart deploys:

Component	Kind	Replicas	Purpose
Server	Deployment	2	HTTP server (REST, MCP, WebSocket)
Worker	Deployment	1	Background tasks (push queue, sweeps)
Postgres	StatefulSet	1	Database (optional — disable if using managed DB)
Redis	Deployment	1	Rate limiting (optional)

Key Values

# Server
server:
  replicas: 2
  image:
    repository: ghcr.io/ottercoders/klaxon-server
    tag: latest
  resources:
    requests: { cpu: 100m, memory: 128Mi }
    limits: { cpu: 500m, memory: 512Mi }

# Worker
worker:
  enabled: true
  replicas: 1

# External database (disable built-in Postgres)
postgres:
  enabled: false # Use your own managed Postgres
secrets:
  databaseUrl: "postgres://user:pass@rds-host:5432/klaxon"

# Ingress
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  hosts:
    - host: klaxon.sh
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: klaxon-tls
      hosts:
        - klaxon.sh

Health Probes

The server deployment configures:

• Liveness: GET /health (always 200)
• Readiness: GET /ready (checks DB connection, returns 503 if down)

The worker uses an exec probe (true) since it has no HTTP port.

Secrets

Create a Kubernetes Secret or set values inline:

secrets:
  databaseUrl: "postgres://..."
  fcmServerKey: "..."
  secretKey: "..."

Or use an existing secret:

postgres:
  auth:
    existingSecret: my-klaxon-secrets

Scaling

• Server: scale horizontally — all replicas share state via Postgres and broadcast events via LISTEN/NOTIFY
• Worker: keep at 1 replica (uses FOR UPDATE SKIP LOCKED for safe concurrent access, but multiple workers are redundant)
• Postgres: use a managed service (RDS, Cloud SQL, etc.) for production
• Redis: single instance is sufficient for rate limiting