Skip to main content

​
Docker Single Node Deployment

Deploy WuKongIM as a single node using Docker Compose for development and small production environments.

​
Overview

Single node deployment is ideal for:
  • Small Applications: Up to 400k daily active users
  • Development Environment: Testing and development
  • Simple Setup: Quick deployment with minimal configuration
  • Cost-Effective: Single server deployment
Scaling: Single node can be easily upgraded to cluster mode later without data migration.

​
Advantages

  • Simple deployment and management
  • Good performance for moderate loads
  • Supports online scaling to cluster
  • Lower resource requirements

​
Disadvantages

  • No automatic failover
  • Manual backup required
  • Single point of failure

​
Prerequisites

Before starting, ensure you have:
1

Linux System

Ubuntu 18.04+ or CentOS 7+ (Ubuntu 20.04+ recommended)
2

Hardware Requirements

  • Minimum: 2 cores, 4GB RAM
  • Recommended: 4 cores, 8GB RAM
3

Docker Installation

Docker 20.10+ and Docker Compose 1.29+
4

Network Access

Ports 5001, 5100, 5200, 5300 available

​
Installation

​
1. Create Installation Directory

# Create directory
mkdir ~/wukongim
cd ~/wukongim

​
2. Create Docker Compose Configuration

Create a docker-compose.yml file with the following content: 
version: '3.7'
services:
  wukongim:
    image: registry.cn-shanghai.aliyuncs.com/wukongim/wukongim:v2
    environment:
      - "WK_CLUSTER_NODEID=1001"
      # - "WK_TOKENAUTHON=true"  # Enable token auth (recommended for production)
      - "WK_CLUSTER_SERVERADDR=YOUR_INTERNAL_IP:11110"  # Internal communication address
      - "WK_TRACE_PROMETHEUSAPIURL=http://prometheus:9090"  # Prometheus monitoring
      - "WK_MODE=release"  # Release mode
      - "WK_EXTERNAL_IP=YOUR_EXTERNAL_IP"  # Server external IP
      - "WK_CLUSTER_APIURL=http://YOUR_INTERNAL_IP:5001"  # Internal API address
      - "WK_INTRANET_TCPADDR=YOUR_INTERNAL_IP:5100"  # Internal TCP address
    healthcheck:
      test: "wget -q -Y off -O /dev/null http://localhost:5001/health > /dev/null 2>&1"
      interval: 10s
      timeout: 10s
      retries: 3
    restart: always
    volumes:
      - ./wukongim_data:/root/wukongim  # Data persistence
    ports:
      - "5001:5001"   # HTTP API
      - "5100:5100"   # TCP connections
      - "5200:5200"   # WebSocket connections
      - "5300:5300"   # Management interface
      - "5172:5172"   # Demo interface
      - "11110:11110" # Cluster communication

  prometheus:
    image: registry.cn-shanghai.aliyuncs.com/wukongim/prometheus:v2.53.1
    volumes:
      - "./prometheus.yml:/etc/prometheus/prometheus.yml"
    ports:
      - "9090:9090"
Important: Replace the following placeholders with your actual values:
  • YOUR_EXTERNAL_IP: Your server’s external IP address
  • YOUR_INTERNAL_IP: Your server’s internal IP address

​
3. Configure Prometheus Monitoring

Create a prometheus.yml file for monitoring: 
global:
  scrape_interval: 10s
  evaluation_interval: 10s

scrape_configs:
  - job_name: wukongim-metrics
    static_configs:
      - targets: ['wukongim:5300']

​
4. Start the Services

# Start WuKongIM and monitoring
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f wukongim

​
Configuration

​
Environment Variables

Key environment variables for single node deployment:
VariableDescriptionExample
WK_CLUSTER_NODEIDUnique node identifier1001
WK_EXTERNAL_IPExternal IP for client connections203.0.113.1
WK_CLUSTER_SERVERADDRInternal communication address10.0.1.100:11110
WK_TOKENAUTHONEnable token authenticationtrue
WK_MODERunning moderelease

​
Security Configuration

For production environments, enable authentication: 
environment:
  - "WK_TOKENAUTHON=true"
  - "WK_MANAGERTOKEN=your-secure-manager-token"

​
Verification

​
1. Health Check

# Check if WuKongIM is running
curl http://localhost:5001/health

# Expected response: {"status":"ok"}

​
2. Get Connection Information

# Get connection details for a user
curl "http://localhost:5001/route?uid=testuser"

# Expected response:
# {
#   "tcp_addr": "YOUR_EXTERNAL_IP:5100",
#   "ws_addr": "ws://YOUR_EXTERNAL_IP:5200"
# }

​
3. Access Management Interface

Open your browser and navigate to:
  • Management Interface: http://YOUR_EXTERNAL_IP:5300
  • Prometheus Monitoring: http://YOUR_EXTERNAL_IP:9090
  • Demo Interface: http://YOUR_EXTERNAL_IP:5172

​
Data Management

​
Backup

# Stop services
docker-compose down

# Backup data directory
tar -czf wukongim-backup-$(date +%Y%m%d).tar.gz wukongim_data/

# Restart services
docker-compose up -d

​
Restore

# Stop services
docker-compose down

# Restore data
tar -xzf wukongim-backup-YYYYMMDD.tar.gz

# Restart services
docker-compose up -d

​
Troubleshooting

​
Common Issues

Check if ports are already in use:
sudo netstat -tulpn | grep :5001
sudo netstat -tulpn | grep :5100
sudo netstat -tulpn | grep :5200
Verify the service is running and healthy:
docker-compose ps
docker-compose logs wukongim
Ensure firewall allows connections:
sudo ufw allow 5001/tcp
sudo ufw allow 5100/tcp
sudo ufw allow 5200/tcp

​
Log Analysis

# View real-time logs
docker-compose logs -f wukongim

# View specific number of log lines
docker-compose logs --tail=100 wukongim

# Export logs to file
docker-compose logs wukongim > wukongim.log

​
Next Steps

Scale to Cluster

Upgrade to multi-node cluster deployment

Configure Authentication

Set up user authentication

API Integration

Start using the WuKongIM API

Monitoring Setup

Set up comprehensive monitoring