Deployment

Choose the cluster objective and runtime medium, then verify every WuKongIM deployment against the same gates.

Start with two questions: Do you accept a single point of failure? Who operates the nodes? The first decides topology; the second decides Docker, Linux, or Kubernetes. A runtime medium does not create high availability by itself.

Every deployment is a cluster

A one-node deployment is a single-node cluster. It still uses the Controller, Slot, Channel, routing, and storage paths. There is no standalone mode that bypasses cluster semantics.

Only evaluating WuKongIM? Use the Quickstart. This section is for environments that need persistence, observability, and repeatable releases.

1. Choose the topology

Objective	Topology	Next step
Development, validation, or explicit acceptance of one failure point	Single-node cluster	Choose Docker or Linux
Cross-node replication and failure handling	Multi-node cluster	Complete the multi-node design first

A single-node cluster has one Slot/Channel replica, so a node or disk failure interrupts service. Multiple nodes create useful failure domains only when disks, power, or availability zones are independent; three containers on one disk are not three independent replicas.

Three nodes with three replicas have no node headroom. After any node is lost, the others may retain a Raft majority but return 503 from /readyz because replica candidates are insufficient. To retain three eligible replica candidates after one node loss, provide at least four qualified data nodes.

2. Choose the runtime medium

Medium	Fit	Operator ownership
Docker	Existing container build and runtime capability	Images, volumes, network, secrets, and container lifecycle
Linux	Direct host and systemd management	Binary, directory permissions, firewall, and service unit
Kubernetes (Beta)	Mature stateful-workload platform	Final manifests, PVCs, secrets, NetworkPolicy, and release evidence

The repository-root three-node Compose stack is for development validation only. Official versioned container images are documented on the Docker page; these docs still promise no official installation package, Helm chart, or production Kubernetes manifest.

3. Follow one implementation sequence

Freeze the artifact: build every node from the same reviewed commit and record the toolchain and digest.
Complete configuration: use Configuration to confirm TOML, WK_* overrides, node identities, and client advertisements.
Prepare state: give every node an independent data directory or disk, with capacity bounds for logs, plugin state, and metrics.
Start nodes: pass -config /path/to/wukongim.toml explicitly; never depend on the working directory.
Verify the platform: check persistent mounts, external addresses, /healthz, and /readyz.
Verify the cluster: for multiple nodes, also verify membership, routing, end-to-end messaging, reconnect sync, and failure recovery.
Cut over production: complete the Production Checklist.

Shared runtime contract

Every node has a unique node ID, data directory, and reachable transport address.
Keep the physical hash-slot count at 256; replica counts must fit node availability and failure objectives.
Use 0.0.0.0 only for listening, never as a node or client advertisement.
Keep Manager, metrics, debug, benchmark, diagnostics, and transport in controlled network boundaries.
The deployment platform owns DNS, certificates, external Product HTTP authentication, cloud resources, secret distribution, and production cutover.

Admit traffic with `/readyz`

curl --fail http://127.0.0.1:5001/healthz
curl --fail http://127.0.0.1:5001/readyz

/healthz only proves that the process responds. /readyz returns 503 while cluster write routing is unavailable or restore maintenance is active; load balancers, rollout gates, and traffic switches must use /readyz.

Passing a platform page does not make a deployment production-ready. Admit production traffic only after multi-node verification and the production checklist also have owners, evidence, and a rollback path.