Version Upgrade

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

2. Backup Data (Recommended)

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:

Prepare Green Environment: Set up a new environment with the new version
Data Sync: Ensure data is synchronized between blue and green environments
Switch Traffic: Update load balancer to point to green environment
Verify: Confirm everything works correctly
Cleanup: Remove blue environment after successful verification

Canary Deployment

For gradual rollout:

Deploy to Subset: Upgrade only a portion of nodes
Monitor: Watch metrics and logs for issues
Gradual Rollout: Progressively upgrade more nodes
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

Stop services: docker-compose stop
Restore backup: Restore from backup created before upgrade
Revert configuration: Use previous docker-compose.yml
Restart: docker-compose up -d
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

Cluster Scaling Single Node Deployment

Installation & Configuration

Core Concepts

Learning

Description

Upgrade Steps

1. Check Current Version

2. Backup Data (Recommended)

3. Update Docker Compose Configuration

4. Pull New Image

5. Restart Services

6. Verify Upgrade

Rolling Upgrade for Clusters

1. Upgrade One Node at a Time

2. Verify Cluster Health

Upgrade Strategies

Blue-Green Deployment

Canary Deployment

Rollback Procedures

1. Quick Rollback

2. Data Rollback (if needed)

Upgrade Checklist

Pre-Upgrade

During Upgrade

Post-Upgrade

Troubleshooting

Common Issues

Recovery Steps

Best Practices

Planning

Execution

Automation

Next Steps

Monitoring Setup

Performance Tuning

Best Practices

Cluster Management

​Description

​Upgrade Steps

​1. Check Current Version

​2. Backup Data (Recommended)

​3. Update Docker Compose Configuration

​4. Pull New Image

​5. Restart Services

​6. Verify Upgrade

​Rolling Upgrade for Clusters

​1. Upgrade One Node at a Time

​2. Verify Cluster Health

​Upgrade Strategies

​Blue-Green Deployment

​Canary Deployment

​Rollback Procedures

​1. Quick Rollback

​2. Data Rollback (if needed)

​Upgrade Checklist

​Pre-Upgrade

​During Upgrade

​Post-Upgrade

​Troubleshooting

​Common Issues

​Recovery Steps

​Best Practices

​Planning

​Execution

​Automation

​Next Steps

Monitoring Setup

Performance Tuning

Best Practices

Cluster Management

Description

Upgrade Steps

1. Check Current Version

2. Backup Data (Recommended)

3. Update Docker Compose Configuration

4. Pull New Image

5. Restart Services

6. Verify Upgrade

Rolling Upgrade for Clusters

1. Upgrade One Node at a Time

2. Verify Cluster Health

Upgrade Strategies

Blue-Green Deployment

Canary Deployment

Rollback Procedures

1. Quick Rollback

2. Data Rollback (if needed)

Upgrade Checklist

Pre-Upgrade

During Upgrade

Post-Upgrade

Troubleshooting

Common Issues

Recovery Steps

Best Practices

Planning

Execution

Automation

Next Steps