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
Version | Release Date | Support Status | Migration Required |
---|---|---|---|
v2.0.x | 2024-Q2 | Current | From v1.8+ |
v1.9.x | 2024-Q1 | Maintenance | Minor updates |
v1.8.x | 2023-Q4 | Maintenance | From v1.6+ |
v1.7.x | 2023-Q3 | End of Life | Major migration |
v1.6.x | 2023-Q2 | End of Life | Major 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
-
Authentication System Overhaul
- JWT token format changed
- New role-based access control (RBAC)
- Multi-factor authentication added
-
API Changes
/v1/chat
endpoint deprecated (use/v1/chat/completions
)- New channel management API
- Updated webhook payload format
-
Database Schema Changes
- New tables:
roles
,permissions
,user_roles
- Modified tables:
users
,channels
,conversations
- New tables:
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
- New File Processing Engine
- Enhanced Analytics Dashboard
- 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.