Version Upgrade

WuKongIM Linux version upgrade guide

Upgrade

WuKongIM supports smooth upgrades on Linux systems, 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

Single Node Upgrade

1. Check Current Version

First, check your current WuKongIM version:

# Check running version
./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 WuKongIM service
./wukongim 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. Download New Version

AMD64

curl -L -o wukongim_new https://github.com/WuKongIM/WuKongIM/releases/download/latest/wukongim-linux-amd64

4. Replace Executable File

# Make new executable file executable
chmod +x wukongim_new

# Backup old executable
mv wukongim wukongim_old

# Replace with new version
mv wukongim_new wukongim

5. Start Service

# Start with existing configuration
./wukongim --config wk.yaml -d

6. Verify Upgrade

# Check service status
ps aux | grep wukongim

# Verify version
./wukongim version

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

# Test API functionality
curl http://localhost:5001/version

Multi-Node Cluster Upgrade

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

1. Upgrade One Node at a Time

# On node1
./wukongim stop
# Replace executable file (same steps as single node)
./wukongim --config wk.yaml -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

Advanced Upgrade Strategies

Blue-Green Deployment

For critical production environments:

1. Prepare Green Environment: Set up new servers 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

Rolling Upgrade with Load Balancer

# Remove node from load balancer
# Update nginx configuration to exclude the node
sudo nano /etc/nginx/nginx.conf
sudo systemctl reload nginx

# Upgrade the node
./wukongim stop
# Replace executable
./wukongim --config wk.yaml -d

# Add node back to load balancer
# Update nginx configuration to include the node
sudo systemctl reload nginx

# Repeat for other nodes

Rollback Procedures

If issues occur during upgrade, you can rollback:

1. Quick Rollback

# Stop current version
./wukongim stop

# Restore old executable
mv wukongim wukongim_failed
mv wukongim_old wukongim

# Restart with old version
./wukongim --config wk.yaml -d

2. Data Rollback (if needed)

# Stop service
./wukongim 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 service
./wukongim --config wk.yaml -d

Systemd Service Upgrade

If using systemd service:

# Stop service
sudo systemctl stop wukongim

# Replace executable file
sudo cp wukongim_new /path/to/wukongim

# Start service
sudo systemctl start wukongim

# Check status
sudo systemctl status wukongim

# View logs
sudo journalctl -u wukongim -f

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

Service fails to start after upgrade:

# Check logs
tail -f ./wukongim_data/logs/wukongim.log

# Check if executable has proper permissions
ls -la wukongim

# Verify configuration file
cat wk.yaml

Configuration compatibility issues:

# Check configuration syntax
./wukongim --config wk.yaml --check-config

# Compare with default configuration
./wukongim --help

Data migration issues:

# Check data directory permissions
ls -la ./wukongim_data

# Verify data integrity
./wukongim --config wk.yaml --verify-data

Recovery Steps

1. Stop services: ./wukongim stop
2. Restore backup: Restore from backup created before upgrade
3. Revert executable: Use previous version executable
4. Restart: ./wukongim --config wk.yaml -d
5. Verify: Confirm system is working correctly

Automation Scripts

Automated Upgrade Script

#!/bin/bash
# upgrade-wukongim.sh - Automated upgrade script

set -e

NEW_VERSION="$1"
BACKUP_DIR="./backups"
CONFIG_FILE="wk.yaml"

if [ -z "$NEW_VERSION" ]; then
    echo "Usage: $0 <new_version>"
    exit 1
fi

echo "Starting WuKongIM upgrade to version $NEW_VERSION..."

# 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)
cp wukongim $BACKUP_DIR/wukongim_$(date +%Y%m%d_%H%M%S)

# Stop service
echo "Stopping WuKongIM..."
./wukongim stop

# Download new version
echo "Downloading new version..."
curl -L -o wukongim_new https://github.com/WuKongIM/WuKongIM/releases/download/$NEW_VERSION/wukongim-linux-amd64

# Replace executable
echo "Replacing executable..."
chmod +x wukongim_new
mv wukongim wukongim_old
mv wukongim_new wukongim

# Start service
echo "Starting WuKongIM..."
./wukongim --config $CONFIG_FILE -d

# Wait for startup
sleep 10

# Verify upgrade
echo "Verifying upgrade..."
if curl -f http://localhost:5001/health > /dev/null 2>&1; then
    echo "Upgrade successful! WuKongIM is healthy."
    echo "New version: $(./wukongim version)"
else
    echo "Health check failed! Consider rollback."
    exit 1
fi

echo "Upgrade completed successfully!"

Make script executable and use:

chmod +x upgrade-wukongim.sh
./upgrade-wukongim.sh v2.1.0

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

Monitoring

# Monitor system resources during upgrade
top
htop
iostat 1

# Watch WuKongIM logs
tail -f ./wukongim_data/logs/wukongim.log

# Monitor API health
while true; do
  curl -f http://localhost:5001/health && echo " - OK" || echo " - FAIL"
  sleep 5
done

Next Steps

Monitoring Setup

Set up monitoring for upgraded system

Performance Tuning

Optimize performance after upgrade

Cluster Scaling

Learn about cluster scaling

Best Practices

Backup strategies and best practices