Deployment guide

Choose a Sockudo production topology, configuration strategy, and rollout path.

7 min read
View .mdEdit on GitHub

This guide helps you pick a production shape for Sockudo before you pick a platform. It is for anyone taking Sockudo beyond a laptop, from a first single-container deployment to a multi-zone cluster. Read it first, then follow the platform guide that matches the topology you choose.

A good Sockudo deployment starts with the failure model, not the platform logo. Decide whether one process is sufficient, which state must survive a restart, and whether a client may reconnect to a different node. Those decisions determine the adapter, cache, queue, app manager, and history backends.

How a Sockudo cluster fits together

Each Sockudo node holds the WebSocket connections that landed on it. Everything a node cannot answer alone goes through a shared backend:

ClientsLoad balancerSockudo node ASockudo node BHorizontal adapterCache and queueDurable stores
flowchart TB
  C[Clients] --> LB[Load balancer]
  LB --> A[Sockudo node A]
  LB --> B[Sockudo node B]
  A <--> AD[Horizontal adapter]
  B <--> AD
  A --> CQ[Cache and queue]
  B --> CQ
  A --> DS[Durable stores]
  B --> DS

Each backend exists for a different reason, which is why they are configured separately:

BackendWhat it doesWhy it must be shared across nodes
AdapterFans a publish out to every node with matching subscribers, and answers cross-node queries such as channel occupancy and presence.A client on node A must receive an event published through node B.
CacheHolds coordination state such as idempotency keys and cached channel data.A retried publish can land on a different node and must still be deduplicated.
Rate limiterCounts requests against per-app and per-client limits.Limits enforced per node multiply by the node count.
QueueCarries webhook and push jobs.Work enqueued on a node that dies should still be delivered.
App managerStores app IDs, keys, secrets, and policy.Every node must agree on which apps exist and what they may do.
History and version storesPersist Protocol V2 history, recovery data, and mutable-message versions.Recovery and mutations must work when a client reconnects to another node.

You can mix drivers. A common pattern is a NATS adapter for fanout with Redis for cache, queue, and rate limits, plus PostgreSQL for apps and history.

Choose a topology

DeploymentGood fitRuntime backendsMain limitation
One process, memory onlyLocal development, demos, CILocal adapter, memory cache, queue, app manager, historyRestart loses process-local state; no failover.
One production VMSmall stable workload with a simple operational modelLocal adapter; static apps or a durable app manager; optional durable historyThe host is one failure domain.
Multiple nodes with RedisMost regional production workloadsRedis adapter, cache, queue, and rate limiter; shared app manager when apps change dynamicallyRedis availability and capacity become part of the realtime path.
Multiple nodes with NATSHigh fanout or high subscription churnNATS adapter, Redis cache, durable queue and app managerNATS carries fanout, but coordination and durable features still need shared stores.
Durable Protocol V2 clusterRecovery, history, mutable messages, annotations, AI TransportShared adapter and cache plus durable history and version storesMore write amplification and more dependencies to operate.
Managed/serverless container platformModerate socket counts with platform-managed rollout and scalingShared adapter and stores from the first replicaPlatform connection duration, concurrency, and node-tuning limits apply.

Memory drivers are not shared because several processes use identical configuration. Every multi-node deployment needs a horizontal adapter. Any feature whose correctness crosses nodes also needs its documented shared authority.

See Scaling for the cross-node semantics of each adapter.

A conventional regional cluster has:

  • at least two Sockudo instances spread across failure domains
  • a load balancer that supports WebSocket upgrades and has a deliberate idle timeout
  • Redis or another supported horizontal adapter
  • a shared Redis or Redis Cluster cache for coordination, idempotency, and distributed rate limits
  • durable app storage if app records change at runtime
  • a durable queue when webhook or push work must survive a node failure
  • durable history and version storage when Protocol V2 recovery or mutable state must cross nodes
  • metrics, structured logs, readiness checks, and a tested drain path

Sticky sessions are not required for basic pub/sub. With a shared adapter, any node can serve any client. They can still reduce reconnect churn, but a Protocol V2 reconnect to a different node recovers only when the replay state is available through a shared backend. Start with Scaling for cross-node semantics and Security for network and secret boundaries.

Configuration strategy

Use three layers with distinct responsibilities:

  1. Put stable structure in a version-controlled TOML or JSON file: enabled features, driver choices, limits, queue reliability, history retention, and per-app policy.
  2. Put environment-specific addresses and non-secret switches in deployment variables or a generated config file.
  3. Inject app secrets, database passwords, broker credentials, and provider keys from the platform’s secret store.

The split keeps reviews meaningful: a pull request that changes a driver or a limit is visible in Git, while credentials rotate without a code change and never appear in the repository.

Sockudo does not treat environment variables as a complete alternative syntax for every nested configuration field. Complex policy and multi-app definitions belong in a file or persistent app manager. Config files can reference environment variables with ${VAR} placeholders when a nested value must come from the environment. See Static configuration for exact precedence and equivalent TOML and JSON examples.

Workload questions to answer first

Document these inputs before choosing instance sizes:

InputWhy it matters
Peak concurrent sockets and reconnect surgeSets file descriptor, memory, load-balancer, and admission budgets.
Messages per second and average payloadSets CPU, network, adapter, and serialization load.
Subscribers per publishDistinguishes ingest throughput from fanout throughput.
Public, private, and presence mixAdds authentication, membership, and transition work.
Subscription churnCan dominate otherwise quiet chat or room workloads.
Protocol V1 or V2 featuresRecovery, deltas, filtering, history, and mutations change state and compute costs.
Retention and recovery objectivesSelects memory buffers versus durable stores.
Client geographyChanges handshake time, RTT, reconnect behavior, and apparent benchmark throughput.

Capacity planning turns these answers into per-node limits.

Rollout sequence

  1. Build or pin one exact Sockudo image or binary version and the required Cargo features. Verify with sockudo --version, which prints the version, for example sockudo 5.2.0.
  2. Validate the resolved config in staging. Startup must log explicit configuration applied and applied environment variable overrides, and curl -fsS http://<node>:6001/up/<app-id> must print OK.
  3. Load test from realistic client regions and confirm the load generators are not saturated.
  4. Set a per-node SOCKUDO_MAX_CONNECTIONS below the measured safe ceiling. Above 95% of that value, /ready returns 503 CAPACITY so a load balancer can stop routing new clients.
  5. Deploy at minimum capacity before enabling autoscaling.
  6. Remove a node while traffic is active and verify that its clients reconnect elsewhere and that recovery succeeds.
  7. Fail or pause each shared dependency and verify readiness, alerts, and backpressure.
  8. Roll in small batches while watching connection churn, adapter errors, and recovery failures.

Production gate

Do not call a deployment ready until all of these are true:

  • /live is used for liveness and startup checks
  • /up, /up/<app-id>, or the capacity-aware /ready is used for readiness
  • the load balancer idle timeout and Sockudo heartbeat behavior have been tested together
  • file descriptor limits have been checked in the actual process or container
  • credentials are absent from images, ConfigMaps, command lines, and logs
  • every replica has a unique INSTANCE_PROCESS_ID, stable across restarts when logs, metrics, or Iggy consumers depend on it
  • adapter.fallback_to_local is false on every multi-node deployment
  • multi-node drivers and feature flags pass Sockudo startup validation
  • termination grace exceeds Sockudo’s shutdown grace period plus its drain budgets
  • load testing includes connect, steady-state, fanout, churn, and reconnect phases
  • dashboards distinguish a Sockudo bottleneck from the load generator, load balancer, NAT, or broker

Next steps