​

Migration Guides

Comprehensive guides for migrating between major versions of the Plugged.in platform. Follow these guides carefully to ensure a smooth transition.

​

Latest Migration

​

v2.12.0 Migration Guide

​

Upload Context Metadata Migration

What’s New:

• Upload context metadata tracking (purpose, related documents, notes)
• Upload method detection (drag-drop vs file-picker)
• Enhanced UploadMetadataPanel component

Migration Steps:

1. Update Dependencies
   Copy

   # Update to latest version
   pnpm update pluggedin-app@2.12.0
   

2. Database Migration
   Copy

   # Generate new migration
   pnpm db:generate
   
   # Apply migration
   pnpm db:migrate
   

3. Environment Variables
   Copy

   # No new environment variables required for v2.12.0
   

4. Testing
   Copy

   # Test upload functionality
   pnpm test
   
   # Verify metadata tracking
   pnpm test:integration
   

Breaking Changes:

• None

Estimated Downtime: < 5 minutes

​

Major Version Migrations

​

v2.10.0 Migration Guide

​

Security & Performance Overhaul

What’s New:

• Complete encryption system overhaul
• Enhanced security audit compliance
• Performance optimizations (10x faster queries)
• Custom Instructions UI improvements

Migration Steps:

1. Pre-Migration Backup
   Copy

   # Create database backup
   pg_dump pluggedin_db > backup_v2.9.0.sql
   
   # Backup uploads directory
   cp -r uploads uploads_backup
   

2. Update Dependencies
   Copy

   pnpm update pluggedin-app@2.10.0
   pnpm update pluggedin-mcp@1.8.0
   

3. Environment Variables Update
   Copy

   # Add new security variables
   NEXTAUTH_SECRET=new_random_secret
   NEXTAUTH_URL=https://your-domain.com
   
   # Database SSL (recommended)
   DATABASE_SSL=true
   DATABASE_SSL_CERT_PATH=/path/to/ca-cert.pem
   

4. Database Migration
   Copy

   # Generate migration files
   pnpm db:generate
   
   # Apply migrations
   pnpm db:migrate
   

5. Encryption Migration ⚠️ Critical Step
   Copy

   # Run encryption migration script
   pnpm migrate:encryption
   
   # Verify encryption migration
   pnpm test:encryption-migration
   

6. Post-Migration Verification
   Copy

   # Test all functionality
   pnpm test
   
   # Verify security headers
   curl -I https://your-domain.com | grep -E "(X-Frame-Options|X-Content-Type-Options|Strict-Transport-Security)"
   
   # Check performance improvements
   pnpm test:performance
   

Breaking Changes:

• Password hashing algorithm changed from bcrypt to argon2
• Some legacy API endpoints deprecated
• Enhanced CSP may affect custom scripts

Estimated Downtime: 15-30 minutes

​

v2.9.0 Migration Guide

​

UUID Tool Prefixing & Security Release

What’s New:

• Automatic UUID tool prefixing for collision prevention
• Slug-based server identification system
• Security patches for encryption vulnerabilities

Migration Steps:

1. Security Preparation
   Copy

   # Backup before security migration
   pg_dump pluggedin_db > backup_pre_security.sql
   

2. Update Dependencies
   Copy

   pnpm update pluggedin-app@2.9.0
   

3. Environment Variables
   Copy

   # No new variables required
   # Existing variables remain compatible
   

4. Database Migration
   Copy

   # Apply security patches
   pnpm db:migrate
   
   # Run slug generation for existing servers
   pnpm migrate:slugs
   

5. Verification
   Copy

   # Test tool name collision resolution
   pnpm test:tool-collision
   
   # Verify slug uniqueness
   pnpm test:slug-uniqueness
   

Breaking Changes:

• Tool names now include UUID prefixes
• Server URLs may include slugs

Estimated Downtime: 5-10 minutes

​

v2.8.0 Migration Guide

​

AI Document Exchange (RAG v2)

What’s New:

• AI document creation and management
• Complete version history tracking
• Advanced search capabilities
• Multi-format support with validation

Migration Steps:

1. Pre-Migration Setup
   Copy

   # Ensure sufficient disk space for document storage
   df -h uploads/
   
   # Backup existing RAG data
   cp -r rag_data rag_data_backup
   

2. Update Dependencies
   Copy

   pnpm update pluggedin-app@2.8.0
   pnpm update pluggedin-mcp@1.8.0
   

3. Environment Variables
   Copy

   # Document storage configuration
   MAX_DOCUMENT_SIZE=10485760  # 10MB
   ALLOWED_DOCUMENT_TYPES=pdf,txt,md,json,html,jpg,png
   RAG_V2_ENABLED=true
   

4. Database Migration
   Copy

   # Apply RAG v2 schema changes
   pnpm db:migrate
   
   # Initialize vector search
   pnpm rag:init
   

5. MCP Proxy Configuration
   Copy

   # Update MCP proxy to use RAG v2 tools
   cd pluggedin-mcp
   pnpm update
   pnpm build
   

6. Testing
   Copy

   # Test document upload and search
   pnpm test:documents
   
   # Verify AI document creation
   pnpm test:ai-documents
   
   # Test semantic search
   pnpm test:rag-search
   

Breaking Changes:

• RAG v1 APIs deprecated in favor of v2
• Document storage format changes
• New MCP tools replace old ones

Estimated Downtime: 10-20 minutes

​

v2.7.0 Migration Guide

​

Registry v2 & OAuth Integration

What’s New:

• MCP Registry v2 with GitHub authentication
• Smart Server Wizard with repository analysis
• OAuth integration for MCP servers
• Trending servers and analytics

Migration Steps:

1. OAuth Setup
   Copy

   # Configure OAuth providers
   # GitHub OAuth app setup required
   # Linear OAuth app setup required
   

2. Update Dependencies
   Copy

   pnpm update pluggedin-app@2.7.0
   pnpm update pluggedin-mcp@1.4.0
   

3. Environment Variables
   Copy

   # OAuth Configuration
   GITHUB_CLIENT_ID=your_github_client_id
   GITHUB_CLIENT_SECRET=your_github_client_secret
   LINEAR_CLIENT_ID=your_linear_client_id
   LINEAR_CLIENT_SECRET=your_linear_client_secret
   
   # Registry Configuration
   REGISTRY_V2_ENABLED=true
   TRENDING_ANALYTICS_ENABLED=true
   

4. Database Migration
   Copy

   # Apply OAuth and registry schema
   pnpm db:migrate
   
   # Initialize OAuth tables
   pnpm oauth:init
   

5. Registry Migration
   Copy

   # Migrate to Registry v2
   pnpm registry:migrate-v2
   
   # Test registry connectivity
   pnpm test:registry
   

6. MCP Proxy Update
   Copy

   cd pluggedin-mcp
   pnpm build
   pnpm test
   

Breaking Changes:

• Registry API endpoints changed
• OAuth flow replaces API key auth for some servers

Estimated Downtime: 20-40 minutes

​

Migration Best Practices

​

Pre-Migration Checklist

• Create full database backup
• Backup all uploaded files and documents
• Test migration on staging environment first
• Notify users of expected downtime
• Prepare rollback plan

​

Post-Migration Verification

• Verify all API endpoints respond correctly
• Test MCP server connections
• Check document upload and search functionality
• Verify OAuth integrations work
• Test notification system
• Monitor performance metrics

​

Rollback Procedures

If issues occur during migration:

1. Immediate Rollback
   Copy

   # Restore database
   psql pluggedin_db < backup_pre_migration.sql
   
   # Restore files
   rm -rf uploads && mv uploads_backup uploads
   
   # Restart services
   pm2 restart all
   

2. Gradual Rollback
   Copy

   # Downgrade one version at a time
   pnpm update pluggedin-app@2.11.0
   pnpm db:migrate:down
   

​

Getting Help

​

Support Resources

• Documentation: docs.plugged.in
• GitHub Issues: Report migration issues
• Community: GitHub Discussions
• Email Support: migration-support@plugged.in

​

Emergency Contacts

• Critical Issues: security@plugged.in
• Enterprise Support: enterprise@plugged.in
• Phone Support: Available for enterprise customers

​

Migration Timeline

​

Version Support Policy

• Current Version: Full support and active development
• Previous Version: Security updates and critical bug fixes
• Older Versions: Community support only
• End of Life: No support provided

For detailed information about each version’s features and changes, see the Changelog.