Skip to main content
WuKongIM offers flexible deployment options to suit different environments and requirements. Choose the method that best fits your infrastructure and scaling needs.

​
Deployment Options

Docker Compose

Quick setup for development and small production deployments

Kubernetes

Cloud-native deployment with automatic scaling and management

Linux Binary

Direct installation on Linux servers for maximum control

​
Single Node vs Cluster Deployment

​
Single Node Deployment

Advantages:
  • Simple deployment and management
  • Good performance for moderate loads
  • Easy to upgrade to cluster later
  • Lower resource requirements
Disadvantages:
  • No automatic failover
  • Manual backup required
  • Single point of failure
Best for:
  • Development environments
  • Small to medium applications (up to 400k daily active users)
  • Applications with relaxed availability requirements

​
Cluster Deployment

Advantages:
  • High availability with automatic failover
  • Automatic data replication and backup
  • Load balancing across nodes
  • Horizontal scaling capabilities
Disadvantages:
  • More complex setup and management
  • Requires multiple servers
  • Higher resource overhead
Best for:
  • Production environments
  • Large applications (1M+ daily active users)
  • Mission-critical applications requiring high availability

​
Hardware Requirements

​
Single Node Deployment

For up to 400k daily active users:
  • Minimum
  • CPU: 2 cores
  • Memory: 8GB RAM
  • Storage: SSD recommended
  • Network: 1Gbps

​
Cluster Deployment

For 1M+ daily active users (3-node cluster):
  • Per Node
  • Total Cluster
  • CPU: 4+ cores
  • Memory: 16GB+ RAM
  • Storage: NVMe SSD
  • Network: 10Gbps

​
Network Requirements

​
Ports

WuKongIM uses the following ports by default:
PortProtocolPurposeRequired
5001HTTPREST APIYes
5100TCPClient connectionsYes
5200WebSocketWeb client connectionsYes
5210WSSSecure WebSocketOptional
5300HTTPManagement interfaceOptional
11110TCPCluster communicationCluster only

​
Firewall Configuration

  • Single Node
  • Cluster
# Allow client connections
ufw allow 5001/tcp  # API
ufw allow 5100/tcp  # TCP clients
ufw allow 5200/tcp  # WebSocket clients
ufw allow 5210/tcp  # WSS (if using SSL)

​
Geographic Distribution

​
Supported Configurations

Current Limitation: Cross-region data node deployment is not supported. However, proxy nodes can be deployed globally.
  • Data Nodes: Must be in the same region/datacenter
  • Proxy Nodes: Can be deployed globally for reduced latency
  • Client Routing: Automatic routing to nearest proxy node

​
Multi-Region Architecture

​
Choosing Your Deployment Method

​
Decision Matrix

FactorDocker ComposeKubernetesLinux Binary
Ease of Setup⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Production Ready⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Scaling⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Monitoring⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Resource Usage⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐

​
Recommendations

  • Development
  • Small Production
  • Large Production
Docker Compose - Quick setup for local development and testing
# Get started in minutes
curl -O https://raw.githubusercontent.com/WuKongIM/WuKongIM/main/docker-compose.yml
docker-compose up -d

​
Next Steps

Choose your deployment method and follow the detailed installation guide:

Docker Compose Setup

Start with Docker for quick deployment

Kubernetes Setup

Deploy on Kubernetes cluster

Linux Installation

Install directly on Linux servers

​
Common Questions

Yes! WuKongIM supports online migration from single node to cluster deployment without downtime. The process involves adding new nodes and redistributing data automatically.
Data nodes store and process messages, while proxy nodes handle client connections and route requests to data nodes. This separation allows for better scaling and geographic distribution.
For single node deployments, no load balancer is needed. For cluster deployments, WuKongIM includes built-in load balancing, but you may want an external load balancer for additional features like SSL termination.