CoAI LogoCoAI.Dev
Reference

Migration Guide

Upgrading and migration instructions for CoAI.Dev versions

Migration Guide

Comprehensive guide for upgrading CoAI.Dev versions, migrating between platforms, and handling breaking changes.

Version Compatibility

VersionRelease DateSupport StatusMigration Required
v2.0.x2024-Q2CurrentFrom v1.8+
v1.9.x2024-Q1MaintenanceMinor updates
v1.8.x2023-Q4MaintenanceFrom v1.6+
v1.7.x2023-Q3End of LifeMajor migration
v1.6.x2023-Q2End of LifeMajor migration

Migration Planning

Always test migrations in a staging environment first. Major version upgrades may require database schema changes and configuration updates.

Pre-Migration Checklist

Before Starting Migration

Backup Current System

#!/bin/bash
# backup-system.sh
 
BACKUP_DIR="/backups/migration-$(date +%Y%m%d-%H%M%S)"
mkdir -p $BACKUP_DIR
 
# Database backup
mysqldump -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD \
  --single-transaction --routines --triggers \
  chatnio > $BACKUP_DIR/database.sql
 
# File storage backup
tar -czf $BACKUP_DIR/storage.tar.gz /storage/
 
# Configuration backup
cp -r /opt/chatnio/config $BACKUP_DIR/
cp /opt/chatnio/.env $BACKUP_DIR/
 
# Docker configuration (if using Docker)
cp docker-compose.yml $BACKUP_DIR/
docker save programzmh/chatnio:current > $BACKUP_DIR/current-image.tar
 
echo "Backup completed: $BACKUP_DIR"

Check System Requirements

# Check current version
curl http://localhost:8000/v1/system/version
 
# Check system resources
free -h
df -h
docker --version
docker-compose --version
 
# Check dependencies
mysql --version
redis-cli --version
nginx -v

Review Breaking Changes

# Download migration notes
curl -s https://api.github.com/repos/coaidev/coai/releases | \
  jq -r '.[].body' | grep -A 10 "BREAKING CHANGES"
 
# Check deprecated features
grep -r "deprecated" /opt/chatnio/config/

Version-Specific Migrations

Upgrading to v2.0.x

Major Version Upgrade

v2.0 introduces significant changes including new authentication system, updated API endpoints, and database schema modifications.

Breaking Changes in v2.0

  1. Authentication System Overhaul

    • JWT token format changed
    • New role-based access control (RBAC)
    • Multi-factor authentication added
  2. API Changes

    • /v1/chat endpoint deprecated (use /v1/chat/completions)
    • New channel management API
    • Updated webhook payload format
  3. Database Schema Changes

    • New tables: roles, permissions, user_roles
    • Modified tables: users, channels, conversations

Migration Steps for v2.0

Update Configuration

# config/v2-migration.yml
migration:
  from_version: "1.9.x"
  to_version: "2.0.x"
  
auth:
  # New authentication settings
  jwt:
    algorithm: "RS256"  # Changed from HS256
    public_key_file: "/certs/public.pem"
    private_key_file: "/certs/private.pem"
  
  rbac:
    enabled: true
    default_role: "user"
  
  mfa:
    enabled: false  # Set to true to enable MFA
    issuer: "CoAI.Dev"
 
api:
  # API versioning
  versions:
    - "v1"  # Legacy support
    - "v2"  # New version
  default_version: "v2"
 
channels:
  # New channel format
  format_version: 2
  health_check_enabled: true
  load_balancing: "round_robin"

Run Database Migration

#!/bin/bash
# migrate-to-v2.sh
 
# Stop services
systemctl stop chatnio
 
# Backup database
mysqldump -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio > pre-v2-backup.sql
 
# Run migration script
curl -sL https://raw.githubusercontent.com/coaidev/coai/v2.0/migrations/v1-to-v2.sql | \
  mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio
 
# Verify migration
mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio \
  -e "SELECT table_name FROM information_schema.tables WHERE table_schema='chatnio' AND table_name IN ('roles', 'permissions', 'user_roles');"
 
echo "Database migration completed"

Update Application

# For Docker deployment
docker pull programzmh/chatnio:v2.0.0
docker-compose down
docker-compose up -d
 
# For manual deployment
wget https://github.com/coaidev/coai/releases/download/v2.0.0/chatnio-linux-amd64
chmod +x chatnio-linux-amd64
sudo mv chatnio-linux-amd64 /usr/local/bin/chatnio
 
# Start service
systemctl start chatnio

Migrate User Roles

#!/bin/bash
# migrate-user-roles.sh
 
# Default role assignment for existing users
mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio << EOF
-- Create default roles
INSERT IGNORE INTO roles (name, description, permissions) VALUES 
('admin', 'Administrator', '["*"]'),
('user', 'Regular User', '["chat:use", "files:upload"]');
 
-- Assign roles to existing users
INSERT INTO user_roles (user_id, role_id)
SELECT u.id, r.id 
FROM users u, roles r 
WHERE r.name = CASE WHEN u.is_admin = 1 THEN 'admin' ELSE 'user' END
AND NOT EXISTS (SELECT 1 FROM user_roles ur WHERE ur.user_id = u.id);
 
-- Remove old admin column
ALTER TABLE users DROP COLUMN is_admin;
EOF
 
echo "User roles migrated"

Upgrading to v1.9.x

Changes in v1.9

  1. New File Processing Engine
  2. Enhanced Analytics Dashboard
  3. Improved Channel Health Monitoring

Migration Steps for v1.9

# Simple upgrade - backward compatible
docker pull programzmh/chatnio:v1.9.x
docker-compose down
docker-compose up -d
 
# Update configuration for new features
cat >> .env << EOF
# New file processing settings
FILE_PROCESSING_ENGINE=v2
OCR_ENABLED=true
OCR_LANGUAGES=eng,fra,deu,spa
 
# Enhanced analytics
ANALYTICS_RETENTION_DAYS=90
ANALYTICS_DETAILED_LOGS=true
EOF
 
systemctl restart chatnio

Platform Migrations

Docker to Kubernetes

Export Current Configuration

# Extract configuration from Docker
docker inspect chatnio | jq '.[0].Config.Env' > docker-env.json
 
# Convert to Kubernetes ConfigMap format
cat > configmap.yaml << EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: chatnio-config
data:
$(cat docker-env.json | jq -r '.[] | "  " + . ' | sed 's/=/: "/' | sed 's/$/"/')
EOF

Create Kubernetes Manifests

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: chatnio
spec:
  replicas: 3
  selector:
    matchLabels:
      app: chatnio
  template:
    metadata:
      labels:
        app: chatnio
    spec:
      containers:
      - name: chatnio
        image: programzmh/chatnio:latest
        envFrom:
        - configMapRef:
            name: chatnio-config
        - secretRef:
            name: chatnio-secrets
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: storage
          mountPath: /storage
        - name: logs
          mountPath: /logs
      volumes:
      - name: storage
        persistentVolumeClaim:
          claimName: chatnio-storage
      - name: logs
        persistentVolumeClaim:
          claimName: chatnio-logs
 
---
apiVersion: v1
kind: Service
metadata:
  name: chatnio-service
spec:
  selector:
    app: chatnio
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Migrate Data

# Copy data from Docker volumes
docker run --rm -v chatnio_storage:/from -v $(pwd):/to alpine \
  sh -c "cd /from && tar cf - . | (cd /to && tar xf -)"
 
# Create Kubernetes PVCs and copy data
kubectl apply -f pvc.yaml
kubectl cp ./storage chatnio-pod:/storage/

Cloud Provider Migration

# Export AWS resources
aws rds describe-db-snapshots --db-instance-identifier chatnio-db
aws s3 sync s3://chatnio-storage ./storage-backup/
 
# Create GCP resources
gcloud sql instances create chatnio-db --database-version=MYSQL_8_0
gcloud storage buckets create gs://chatnio-storage-gcp
 
# Restore data
gcloud sql import sql chatnio-db gs://migration-bucket/database.sql
gcloud storage cp -r ./storage-backup/* gs://chatnio-storage-gcp/
 
# Update configuration
export MYSQL_HOST=new-gcp-instance-ip
export STORAGE_TYPE=gcs
export GCS_BUCKET=chatnio-storage-gcp

Database Migrations

Schema Version Management

-- Create migration tracking table
CREATE TABLE IF NOT EXISTS schema_migrations (
    version VARCHAR(255) PRIMARY KEY,
    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    description TEXT
);
 
-- Check current schema version
SELECT version, applied_at FROM schema_migrations ORDER BY applied_at DESC LIMIT 1;

Manual Migration Scripts

#!/bin/bash
# manual-migration.sh
 
CURRENT_VERSION=$(mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio \
  -N -e "SELECT version FROM schema_migrations ORDER BY applied_at DESC LIMIT 1" 2>/dev/null || echo "1.0.0")
 
TARGET_VERSION="2.0.0"
 
echo "Current version: $CURRENT_VERSION"
echo "Target version: $TARGET_VERSION"
 
# Define migration path
case $CURRENT_VERSION in
  "1.6.0")
    echo "Migrating from 1.6.0 to 1.7.0..."
    mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio < migrations/1.6-to-1.7.sql
    ;&
  "1.7.0")
    echo "Migrating from 1.7.0 to 1.8.0..."
    mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio < migrations/1.7-to-1.8.sql
    ;&
  "1.8.0")
    echo "Migrating from 1.8.0 to 1.9.0..."
    mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio < migrations/1.8-to-1.9.sql
    ;&
  "1.9.0")
    echo "Migrating from 1.9.0 to 2.0.0..."
    mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio < migrations/1.9-to-2.0.sql
    ;;
  $TARGET_VERSION)
    echo "Already at target version"
    exit 0
    ;;
  *)
    echo "Unsupported migration path from $CURRENT_VERSION to $TARGET_VERSION"
    exit 1
    ;;
esac
 
echo "Migration completed successfully"

Configuration Migration

Environment Variable Changes

#!/bin/bash
# migrate-config.sh
 
# Backup current configuration
cp .env .env.backup
 
# v2.0 configuration changes
sed -i 's/JWT_SECRET=/SECRET=/g' .env
sed -i 's/OPENAI_KEY=/OPENAI_API_KEY=/g' .env
 
# Add new required variables
cat >> .env << EOF
# New v2.0 settings
RBAC_ENABLED=true
MFA_ENABLED=false
API_VERSION=v2
HEALTH_CHECK_ENABLED=true
METRICS_ENABLED=true
EOF
 
# Remove deprecated variables
sed -i '/LEGACY_AUTH_ENABLED/d' .env
sed -i '/OLD_API_FORMAT/d' .env
 
echo "Configuration migrated to v2.0 format"

Docker Compose Updates

# docker-compose-v2.yml
version: '3.8'
services:
  chatnio:
    image: programzmh/chatnio:v2.0.0
    environment:
      # Updated environment variables
      - SECRET=${SECRET}
      - RBAC_ENABLED=true
      - API_VERSION=v2
    volumes:
      # New volume structure
      - storage:/app/storage
      - logs:/app/logs
      - certs:/app/certs  # New for v2.0
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G
 
  # New services in v2.0
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
 
volumes:
  storage:
  logs:
  certs:
  redis_data:

Data Migration

User Data Migration

-- Migrate user preferences to new format
UPDATE users SET 
  preferences = JSON_OBJECT(
    'theme', COALESCE(JSON_EXTRACT(preferences, '$.theme'), 'auto'),
    'language', COALESCE(JSON_EXTRACT(preferences, '$.language'), 'en'),
    'default_model', COALESCE(JSON_EXTRACT(preferences, '$.default_model'), 'gpt-3.5-turbo'),
    'temperature', COALESCE(JSON_EXTRACT(preferences, '$.temperature'), 0.7),
    'max_tokens', COALESCE(JSON_EXTRACT(preferences, '$.max_tokens'), 2048)
  )
WHERE preferences IS NOT NULL;
 
-- Migrate conversation metadata
UPDATE conversations SET 
  metadata = JSON_OBJECT(
    'model', model_name,
    'token_count', total_tokens,
    'created_at', created_at,
    'updated_at', updated_at
  )
WHERE metadata IS NULL;

File Storage Migration

#!/bin/bash
# migrate-storage.sh
 
OLD_STORAGE="/old/storage"
NEW_STORAGE="/new/storage"
 
# Create new directory structure
mkdir -p $NEW_STORAGE/{uploads,processed,cache,temp}
 
# Migrate files with new naming convention
find $OLD_STORAGE -type f | while read file; do
  # Extract file metadata
  basename=$(basename "$file")
  extension="${basename##*.}"
  
  # Generate new filename with hash
  new_name=$(echo "$basename" | sha256sum | cut -d' ' -f1)
  new_path="$NEW_STORAGE/uploads/${new_name}.${extension}"
  
  # Copy file and update database
  cp "$file" "$new_path"
  
  # Update database with new path
  mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio \
    -e "UPDATE files SET file_path='uploads/${new_name}.${extension}' WHERE original_name='$basename';"
done
 
echo "File storage migration completed"

Testing Migration

Validation Scripts

#!/bin/bash
# validate-migration.sh
 
echo "=== Migration Validation ==="
 
# Test database connectivity
echo "Testing database connection..."
if mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio -e "SELECT 1;" >/dev/null 2>&1; then
  echo "✅ Database connection successful"
else
  echo "❌ Database connection failed"
  exit 1
fi
 
# Test API endpoints
echo "Testing API endpoints..."
if curl -f http://localhost:8000/health >/dev/null 2>&1; then
  echo "✅ Health endpoint working"
else
  echo "❌ Health endpoint failed"
  exit 1
fi
 
# Test chat functionality
echo "Testing chat functionality..."
response=$(curl -s -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 10
  }')
 
if echo "$response" | jq -e '.choices[0].message.content' >/dev/null 2>&1; then
  echo "✅ Chat functionality working"
else
  echo "❌ Chat functionality failed"
  echo "Response: $response"
  exit 1
fi
 
# Test file upload
echo "Testing file upload..."
test_file=$(mktemp)
echo "This is a test file" > $test_file
 
upload_response=$(curl -s -X POST http://localhost:8000/v1/files \
  -H "Authorization: Bearer $TEST_API_KEY" \
  -F "file=@$test_file" \
  -F "purpose=chat")
 
if echo "$upload_response" | jq -e '.id' >/dev/null 2>&1; then
  echo "✅ File upload working"
else
  echo "❌ File upload failed"
  echo "Response: $upload_response"
fi
 
rm $test_file
 
# Check data integrity
echo "Checking data integrity..."
user_count=$(mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio \
  -N -e "SELECT COUNT(*) FROM users;")
conversation_count=$(mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio \
  -N -e "SELECT COUNT(*) FROM conversations;")
 
echo "Users: $user_count"
echo "Conversations: $conversation_count"
 
if [ "$user_count" -gt 0 ] && [ "$conversation_count" -gt 0 ]; then
  echo "✅ Data integrity check passed"
else
  echo "⚠️  Data integrity check: verify data migration"
fi
 
echo "=== Validation Complete ==="

Rollback Procedures

Emergency Rollback

#!/bin/bash
# emergency-rollback.sh
 
echo "Starting emergency rollback..."
 
# Stop current service
systemctl stop chatnio
 
# Restore database
mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio < /backups/pre-migration-backup.sql
 
# Restore application
docker pull programzmh/chatnio:previous-version
docker-compose down
docker-compose up -d
 
# Restore configuration
cp /backups/.env.backup .env
 
# Restore file storage
rm -rf /storage/*
tar -xzf /backups/storage.tar.gz -C /
 
# Start service
systemctl start chatnio
 
echo "Rollback completed. Please verify system functionality."

Graceful Rollback

#!/bin/bash
# graceful-rollback.sh
 
# Maintenance mode
curl -X POST http://localhost:8000/v1/admin/maintenance \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -d '{"enabled": true, "message": "System maintenance in progress"}'
 
# Export current data (if any new data was created)
mysqldump -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio > post-migration-data.sql
 
# Restore previous version
mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD chatnio < pre-migration-backup.sql
 
# Merge any new data if needed
# (This requires careful analysis of what data can be safely merged)
 
# Disable maintenance mode
curl -X POST http://localhost:8000/v1/admin/maintenance \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -d '{"enabled": false}'
 
echo "Graceful rollback completed"

For complex migrations or custom deployments, consider engaging with our professional services team for migration assistance and validation.