Skip to main content
WuKongIM supports smooth upgrades, ensuring service continuity and data security.

​
Description

WuKongIM’s version numbering follows the major.minor.patch format, for example 1.0.0. When the patch number increases, it indicates bug fixes or minor feature updates; when the minor version increases, it indicates new features; when the major version increases, it indicates incompatible API changes. Therefore, as long as you don’t upgrade major versions, the upgrade process is smooth.
Version Compatibility:
  • Patch updates (e.g., 2.0.1 → 2.0.2): Always safe, includes bug fixes and minor improvements
  • Minor updates (e.g., 2.0.x → 2.1.x): Generally safe, includes new features with backward compatibility
  • Major updates (e.g., 2.x.x → 3.x.x): May include breaking changes, requires careful planning

​
Upgrade Steps

​
1. Check Current Version

First, check your current WuKongIM version: 
# Check running version
docker-compose exec wukongim /wukongim version

# Or check via API
curl http://localhost:5001/version
Before upgrading, it’s recommended to backup your data: 
# Stop services
docker-compose stop

# Create backup
sudo cp -r ./wukongim_data ./wukongim_data_backup_$(date +%Y%m%d)

# Or create compressed backup
sudo tar -czf wukongim_backup_$(date +%Y%m%d).tar.gz ./wukongim_data

​
3. Update Docker Compose Configuration

Modify the image field of the wukongim service in docker-compose.yml to the new version. For example: 
version: '3.7'
services:
  wukongim: # WuKongIM service
    image: registry.cn-shanghai.aliyuncs.com/wukongim/wukongim:v2.1.0 # New version number
    # ... other configurations remain unchanged

​
4. Pull New Image

Use the following command to get the latest image: 
sudo docker-compose pull wukongim

​
5. Restart Services

sudo docker-compose up -d

​
6. Verify Upgrade

After restart, verify the upgrade was successful: 
# Check container status
docker-compose ps

# Check logs
docker-compose logs wukongim

# Verify version
curl http://localhost:5001/version

# Check health status
curl http://localhost:5001/health

​
Rolling Upgrade for Clusters

For cluster deployments, perform rolling upgrades to maintain service availability:

​
1. Upgrade One Node at a Time

# On node1
cd ~/wukongim
# Update docker-compose.yml with new version
docker-compose pull wukongim
docker-compose up -d

# Wait for node1 to be healthy, then proceed to node2
# Repeat for each node

​
2. Verify Cluster Health

# Check cluster status
curl http://load-balancer-ip:15001/cluster/nodes

# Verify all nodes are running the new version
curl http://node1-ip:5001/version
curl http://node2-ip:5001/version
curl http://node3-ip:5001/version

​
Upgrade Strategies

​
Blue-Green Deployment

For critical production environments, consider blue-green deployment:
  1. Prepare Green Environment: Set up a new environment with the new version
  2. Data Sync: Ensure data is synchronized between blue and green environments
  3. Switch Traffic: Update load balancer to point to green environment
  4. Verify: Confirm everything works correctly
  5. Cleanup: Remove blue environment after successful verification

​
Canary Deployment

For gradual rollout:
  1. Deploy to Subset: Upgrade only a portion of nodes
  2. Monitor: Watch metrics and logs for issues
  3. Gradual Rollout: Progressively upgrade more nodes
  4. Full Deployment: Complete upgrade once confident

​
Rollback Procedures

If issues occur during upgrade, you can rollback:

​
1. Quick Rollback

# Revert docker-compose.yml to previous version
# Pull previous image
docker-compose pull wukongim

# Restart with previous version
docker-compose up -d

​
2. Data Rollback (if needed)

# Stop services
docker-compose stop

# Restore backup
sudo rm -rf ./wukongim_data
sudo cp -r ./wukongim_data_backup_YYYYMMDD ./wukongim_data

# Or restore from compressed backup
sudo tar -xzf wukongim_backup_YYYYMMDD.tar.gz

# Restart services
docker-compose up -d

​
Upgrade Checklist

​
Pre-Upgrade

  • Check current version and target version compatibility
  • Review release notes for breaking changes
  • Create data backup
  • Plan maintenance window
  • Notify users of potential downtime
  • Prepare rollback plan

​
During Upgrade

  • Monitor system resources
  • Watch application logs
  • Verify service health endpoints
  • Test critical functionality
  • Monitor cluster status (for multi-node)

​
Post-Upgrade

  • Verify version upgrade successful
  • Test all major features
  • Monitor performance metrics
  • Check data integrity
  • Update documentation
  • Clean up old backups (after verification period)

​
Troubleshooting

​
Common Issues

Container fails to start after upgrade: 
# Check logs for errors
docker-compose logs wukongim

# Check if image was pulled correctly
docker images | grep wukongim

# Verify configuration compatibility
docker-compose config
Data migration issues: 
# Check data directory permissions
ls -la ./wukongim_data

# Verify data integrity
docker-compose exec wukongim ls -la /root/wukongim
Cluster nodes out of sync: 
# Check cluster status
curl http://localhost:5001/cluster/nodes

# Restart problematic nodes
docker-compose restart wukongim

​
Recovery Steps

  1. Stop services: docker-compose stop
  2. Restore backup: Restore from backup created before upgrade
  3. Revert configuration: Use previous docker-compose.yml
  4. Restart: docker-compose up -d
  5. Verify: Confirm system is working correctly

​
Best Practices

​
Planning

  • Test in staging: Always test upgrades in a staging environment first
  • Read release notes: Understand what changes are included
  • Schedule maintenance: Plan upgrades during low-traffic periods
  • Communicate: Inform stakeholders about planned maintenance

​
Execution

  • Monitor closely: Watch logs and metrics during upgrade
  • Upgrade gradually: For clusters, upgrade one node at a time
  • Verify thoroughly: Test all critical functionality after upgrade
  • Keep backups: Maintain backups until upgrade is fully verified

​
Automation

Consider automating upgrades for consistency: 
#!/bin/bash
# upgrade.sh - Automated upgrade script

# Configuration
NEW_VERSION="v2.1.0"
BACKUP_DIR="./backups"
COMPOSE_FILE="docker-compose.yml"

# Create backup
echo "Creating backup..."
mkdir -p $BACKUP_DIR
sudo cp -r ./wukongim_data $BACKUP_DIR/wukongim_data_$(date +%Y%m%d_%H%M%S)

# Update compose file
echo "Updating docker-compose.yml..."
sed -i "s|wukongim:v.*|wukongim:$NEW_VERSION|g" $COMPOSE_FILE

# Pull new image
echo "Pulling new image..."
docker-compose pull wukongim

# Restart services
echo "Restarting services..."
docker-compose up -d

# Verify upgrade
echo "Verifying upgrade..."
sleep 10
curl -f http://localhost:5001/health || echo "Health check failed!"

echo "Upgrade completed!"

​
Next Steps

Monitoring Setup

Set up monitoring for upgraded system

Performance Tuning

Optimize performance after upgrade

Best Practices

Backup strategies and best practices

Cluster Management

Learn about cluster scaling and management