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.
| Layer | What you scale | Result |
|---|---|---|
| Chatto replicas | chatto run server processes | More web, API, and realtime capacity. Rolling deploys. Redundancy if a process fails. |
| NATS cluster | NATS servers with JetStream | More storage and broker capacity. Data survives if a NATS node fails. |
Memory and startup
Section titled “Memory and startup”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.
Requirements
Section titled “Requirements”- 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.
Configuring Chatto for Multiple Replicas
Section titled “Configuring Chatto for Multiple Replicas”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>"CHATTO_NATS_REPLICAS=3CHATTO_NATS_EMBEDDED_ENABLED=falseCHATTO_NATS_CLIENT_URL=nats://nats-1:4222,nats://nats-2:4222,nats://nats-3:4222CHATTO_NATS_CLIENT_AUTH_METHOD=tokenCHATTO_NATS_CLIENT_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.
What You Need to Keep Consistent
Section titled “What You Need to Keep Consistent”| Setting | Must match? | Used for |
|---|---|---|
| NATS client URL and credentials | Yes | Connection to the same NATS deployment |
nats.replicas | Yes | JetStream replica count |
webserver.url | Yes | Absolute links |
webserver.cookie_signing_secret | Yes | Browser-flow cookies and CSRF proofs |
webserver.cookie_encryption_secret | Yes, when set | Browser-flow cookie encryption |
core.secret_key | Yes | Sessions, tokens, OAuth codes, account flows, and invitation codes |
core.assets.signing_secret | Yes | Asset URLs |
livekit.server_id | Yes, in one Chatto server | LiveKit room names |
Scaling NATS Itself
Section titled “Scaling NATS Itself”Give each NATS node a configuration file. Use a unique server_name and the
same routes list on each node:
server_name: nats-1listen: 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.
JetStream Replication
Section titled “JetStream Replication”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.replicas | NATS nodes | Tolerates | Use |
|---|---|---|---|
1 (default) | 1 or more | No node failure | Development, one node |
3 | 3 or more | 1 node failure | Production |
5 | 5 or more | 2 node failures | Critical deployments |
Presence data is in memory only. If NATS loses it, Chatto builds it again automatically.
Load Balancing
Section titled “Load Balancing”- 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.
Health Checks
Section titled “Health Checks”| Endpoint | Probe | Returns 200 when |
|---|---|---|
GET /readyz | Readiness and startup | NATS is connected, JetStream is available, and recovery is complete |
GET /healthz | Liveness | The 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.
Docker Compose
Section titled “Docker Compose”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: 3To change the number of replicas at any time:
docker compose up -d --scale chatto=5Kubernetes
Section titled “Kubernetes”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/chattoimage. - 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: 5livenessProbe: httpGet: path: /healthz port: 4000 periodSeconds: 10startupProbe: httpGet: path: /readyz port: 4000 failureThreshold: 15 periodSeconds: 2Voice 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:
CHATTO_LIVEKIT_SERVER_ID=server-1Chatto 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.
Failure Scenarios
Section titled “Failure Scenarios”| Failure | Effect | Recovery |
|---|---|---|
| One Chatto replica | The 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 nodes | NATS rejects writes because there is no quorum. Some reads can work. | Start the nodes again |
| All NATS nodes | Full outage | Start the cluster again, or restore from a backup |