Skip to content
Chatto v0.5.0

Scaling & High Availability

By default, Chatto runs as one process with an embedded NATS server. This is sufficient for small and medium communities. To get more capacity or redundancy, run several Chatto server processes on an external NATS cluster.

Chatto server processes keep no local state. All persistent data is in NATS JetStream, so any replica can serve any request.

LayerWhat you scaleResult
Chatto replicaschatto run server processesMore web, API, and realtime capacity. Rolling deploys. Redundancy if a process fails.
NATS clusterNATS servers with JetStreamMore storage and broker capacity. Data survives if a NATS node fails.
STATELESS REPLICAS BrowserSvelteKit SPA CaddyLoad Balancer Chattoreplica 1 Chattoreplica 2 Chattoreplica 3 NATS JetStream shared state

Each Chatto replica keeps its own complete read models in memory. More replicas increase request capacity; they do not split that memory requirement. Server history increases memory use and startup work. Projection snapshots reduce the events that a replica must read at startup. Monitor startup duration, readiness, and memory use when you size replicas.

  • An external NATS deployment with JetStream. Use a cluster of 3 or more nodes for high availability. One external NATS server lets replicas share data, but it is a single point of failure.
  • A load balancer that supports WebSockets, such as Caddy, nginx, or Traefik.
  • The same secrets and public URL on all server processes.

Disable embedded NATS and connect every server process to the cluster:

[nats]
replicas = 3
[nats.embedded]
enabled = false
[nats.client]
url = "nats://nats-1:4222,nats://nats-2:4222,nats://nats-3:4222"
auth_method = "token"
token = "<generate-me>"

List all NATS nodes in the URL. If one node is down, the client connects to a different node. For other authentication methods, see Environment Variables.

SettingMust match?Used for
NATS client URL and credentialsYesConnection to the same NATS deployment
nats.replicasYesJetStream replica count
webserver.urlYesAbsolute links
webserver.cookie_signing_secretYesBrowser-flow cookies and CSRF proofs
webserver.cookie_encryption_secretYes, when setBrowser-flow cookie encryption
core.secret_keyYesSessions, tokens, OAuth codes, account flows, and invitation codes
core.assets.signing_secretYesAsset URLs
livekit.server_idYes, in one Chatto serverLiveKit room names

Give each NATS node a configuration file. Use a unique server_name and the same routes list on each node:

server_name: nats-1
listen: 0.0.0.0:4222
jetstream {
store_dir: /data/jetstream
max_mem: 1G
max_file: 50G
}
cluster {
name: chatto
listen: 0.0.0.0:6222
routes: [
nats-route://nats-1:6222
nats-route://nats-2:6222
nats-route://nats-3:6222
]
}
authorization {
token: "<generate-me>"
}

With Docker Compose, give each node its own configuration file and data volume:

services:
nats-1:
image: nats:latest
command: ["--config", "/etc/nats/nats.conf"]
volumes:
- ./nats-1.conf:/etc/nats/nats.conf:ro
- nats1_data:/data
# Add nats-2 and nats-3 with their own files and volumes.

For TLS, route authentication, and cluster sizing, see the NATS clustering and JetStream clustering documentation.

nats.replicas sets how many copies NATS keeps of each Chatto stream, KV bucket, and object store. The value applies to all of them. Use an odd number for quorum:

nats.replicasNATS nodesToleratesUse
1 (default)1 or moreNo node failureDevelopment, one node
33 or more1 node failureProduction
55 or more2 node failuresCritical deployments

Presence data is in memory only. If NATS loses it, Chatto builds it again automatically.

  • Use round-robin. Session affinity is not necessary.
  • Make sure that the load balancer supports long-lived WebSocket connections.

The Docker Compose guide includes a Caddy configuration for this.

EndpointProbeReturns 200 when
GET /readyzReadiness and startupNATS is connected, JetStream is available, and recovery is complete
GET /healthzLivenessThe NATS client can still recover in its five-minute grace period

During a NATS failover or a short outage, /readyz fails and /healthz stays healthy. The load balancer stops sending traffic to the replica, but the replica does not restart. If the NATS client closes permanently, or recovery stays stuck for five minutes, both endpoints fail and the orchestrator can restart the replica.

chatto:
image: ghcr.io/chattocorp/chatto:latest
deploy:
replicas: 3
healthcheck:
test: ["CMD", "wget", "-q", "--spider", "http://localhost:4000/readyz"]
interval: 5s
timeout: 3s
retries: 3

To change the number of replicas at any time:

Terminal window
docker compose up -d --scale chatto=5

Chatto runs on Kubernetes. There are no maintained manifests or Helm charts yet. Use the configuration on this page, and the Docker Compose guide as the most complete example. You need:

  • One or more Chatto replicas with the ghcr.io/chattocorp/chatto image.
  • An external NATS cluster with JetStream. See NATS on Kubernetes.
  • The same secrets on all replicas, for example from one Kubernetes Secret.
  • An ingress for HTTP and WebSocket traffic.
  • Optional services: LiveKit, SMTP or JMAP, Web Push, and S3-compatible storage.

Use these probes:

readinessProbe:
httpGet:
path: /readyz
port: 4000
periodSeconds: 5
livenessProbe:
httpGet:
path: /healthz
port: 4000
periodSeconds: 10
startupProbe:
httpGet:
path: /readyz
port: 4000
failureThreshold: 15
periodSeconds: 2

Voice and Video Calls with Multiple Server Processes

Section titled “Voice and Video Calls with Multiple Server Processes”

If you use LiveKit, set the same livekit.server_id on all replicas of one Chatto server:

Terminal window
CHATTO_LIVEKIT_SERVER_ID=server-1

Chatto adds this value to LiveKit room names. If replicas use different values, members on different replicas can join different LiveKit rooms for the same Chatto room. Use a different value only for a different Chatto server that shares the same LiveKit cluster.

FailureEffectRecovery
One Chatto replicaThe load balancer sends traffic to the other replicas.Automatic
A minority of NATS nodes (for example, 1 of 3)Short leader election. No data loss. Reads and writes continue.Automatic
A majority of NATS nodesNATS rejects writes because there is no quorum. Some reads can work.Start the nodes again
All NATS nodesFull outageStart the cluster again, or restore from a backup