Migrations

• Migration Types
  • Automatic Migrations
  • Manual Migrations
• Understanding the Import Process
  • Import Steps Breakdown
  • Import Status Indicators
  • Migration Process Flow
• Migrations in Progress
  • Taking Action on In-Progress Migrations
• Migration Details
  • Steps Tab
  • Source Details Tab (Automatic Migrations Only)
  • Process Details Tab
  • Destination Details Tab
  • Logs Tab
• Failed Migrations
• Successful Migrations
• Best Practices
  • For Automatic Migrations
  • For Manual Migrations
  • For Large Sites
  • Security Considerations
• Troubleshooting Common Issues
  • Migration Stuck on "Downloading Files"
  • "Cannot Connect to FTP Server"
  • "Database Import Failed"
  • "WordPress Not Found"
  • Plugin Method Fails
• Additional Resources

The Migrations section is the centralized hub for managing WordPress instance imports into PanelAlpha. This migration center allows you to monitor, manage, and troubleshoot all migrations—whether initiated by clients or administrators. You can preview migrations in progress, review successful migrations, and take action on failed migrations.

Key indicator: If you see a red pulsing icon next to the Migrations menu item, immediate attention is required for failed or pending migrations.

Migration Types

PanelAlpha supports two types of migrations:

Automatic Migrations

Automatic migrations are initiated by clients through the Client Area when they choose to import an existing WordPress instance. These migrations use either:

• Plugin-based method: The PanelAlpha WordPress Migrator plugin automates the entire migration process
• FTP/SFTP method: Direct file and database download using FTP credentials

Import methods explained:

1. Simple Method (Plugin):

   • With login credentials: PanelAlpha logs into WordPress admin, installs the plugin, and runs the migration automatically
   • Manual plugin installation: Client downloads and installs the plugin manually, then initiates migration
   • Fully automated file and database transfer
   • Real-time progress updates
   • Recommended for most scenarios

2. Advanced Method (FTP/SFTP):

   • Direct FTP/SFTP connection to source server
   • Downloads WordPress files and database
   • Useful when plugin method is not feasible
   • Requires FTP credentials and path to WordPress installation

Automatic migration features:

• Real-time progress tracking: See which step is currently executing

• Stop capability: Ability to stop an automatic migration at any time

• Source details: View FTP/plugin connection details used for import

• Live logs: Real-time log updates as migration progresses

• Retry on failure: Can retry failed automatic migrations

Key differences from manual migrations:

• Started by clients, not administrators

• Can be stopped mid-process (manual migrations must complete once started)

• Include source connection details (FTP credentials or plugin info)

• Automatic cleanup of source plugin after completion

Manual Migrations

Manual migrations are initiated by administrators when automatic imports fail or when more control over the migration process is needed. This type allows administrators to:

• Handle failed client migrations
• Manually upload files and database backups
• Verify data before proceeding with migration steps
• Retry specific steps independently

To initiate a manual migration of a WordPress website, follow these steps:

1. Click the Manual Migration button at the top of the Migrations page.

2. Fill out the form:
   • Select User: Choose the user who will own the imported instance
   • Select Service: Choose the service (plan and hosting server) where the instance will be created
   • Click Create Instance and Initiate Import

3. After creating the migration, you'll see the Migration Details screen showing FTP credentials and upload instructions.

4. Upload required files:

   • Connect to the provided FTP account using an FTP client
   • Upload two files to the temporary directory:
     • wordpress-files.zip - ZIP archive of all WordPress files
     • database.sql or database.sql.gz - Database dump file

5. Verify uploads:

   • Click the Verify button to confirm files are present and valid
   • PanelAlpha will check file existence and basic integrity

6. Continue migration:

   • Once verification succeeds, click Continue Import
   • The migration will proceed automatically through all remaining steps

File upload requirements for manual migrations:

When uploading files for a manual migration, you need to provide:

1. WordPress Files: A ZIP archive containing all WordPress files

   • Include all files from the WordPress root directory
   • Preserve the directory structure (wp-content, wp-includes, etc.)
   • File must be named: wordpress-files.zip
   • Maximum recommended size: depends on your hosting server limits

2. Database Backup: An SQL dump of the WordPress database

   • Export using phpMyAdmin, WP-CLI, mysqldump, or your preferred tool
   • File must be named: database.sql (or database.sql.gz if compressed)
   • Ensure export includes all WordPress tables
   • Gzip compression is supported and recommended for large databases

Important notes:

• Large file uploads may take significant time depending on connection speed
• Ensure your ZIP archive is not corrupted before uploading (test extraction locally)
• The temporary FTP account will be automatically removed after migration completes
• All uploaded files in the temporary directory will be cleaned up automatically

Understanding the Import Process

Regardless of the import method (automatic or manual), all migrations follow a standardized process with multiple steps. Understanding these steps helps troubleshoot issues and monitor progress effectively.

Import Steps Breakdown

Each import goes through the following steps in sequence:

1. Installing New Instance

   • Creates a new hosting account on the destination server
   • Generates secure username and password
   • Configures account limits and quotas based on the plan
   • Sets up the domain and document root directory structure
   • Applies PHP version settings and web server configuration
   • Creates necessary DNS records (if DNS server is configured)

2. Installing Plugin on New Instance

   • Creates a fresh WordPress installation on destination
   • Installs PanelAlpha WordPress Migrator plugin
   • Configures plugin with migration credentials
   • Prepares destination for receiving migration data
   • Only for plugin-based migrations

3. Preparing New Instance for Migration

   • Creates temporary workspace for file staging
   • Sets up secure directory with restricted permissions
   • Configures temporary FTP account (for manual migrations) with secure password
   • Limited FTP access to temporary directory only
   • Validates hosting server availability and resources

4. Installing Plugin on Migrated Instance

   • Logs into source WordPress admin panel (for plugin method with login)
   • Uploads and activates migration plugin
   • Establishes secure connection to PanelAlpha
   • Only applicable when client provides admin credentials
   • Skipped if client manually installed plugin

5. Preparing Migration

   • Plugin analyzes source WordPress installation
   • Calculates total file and database size
   • Creates migration manifest and checksums
   • Validates source WordPress compatibility
   • Downloads WordPress files and database from source
   • Methods vary based on import type:
     • Plugin method: Direct transfer via plugin API with chunking
     • FTP method: Downloads via FTP/SFTP from source server
     • Manual method: Uses uploaded ZIP and SQL files

6. Running Migration

   • Extracts WordPress files to the domain directory
   • Preserves file permissions and directory structure
   • Creates MySQL/MariaDB database on destination
   • Imports SQL dump into destination database
   • Updates WordPress tables with new URLs and paths using search-replace
   • Updates serialized data correctly
   • Updates wp-config.php with new database credentials
   • Modifies WordPress URL settings (siteurl, home)
   • Configures security keys and salts
   • Clears WordPress cache and transients
   • Validates installation and verifies functionality

7. Cleaning Up Plugins

   • Removes migration plugin from source (if installed automatically)
   • Deletes temporary FTP account used for uploads
   • Removes temporary directory and all staging files
   • Cleans up downloaded archives and database dumps
   • Removes migration artifacts
   • Finalizes import record and sets instance status to active

Post-import automatic actions:

After successful import completion, PanelAlpha automatically performs the following actions:

• Caches instance details: Stores instance information for faster dashboard loading
• Initiates PageSpeed analysis: Scheduled 2 minutes after import to allow site stabilization
• Creates DNS zone and records: If external DNS server is configured in PanelAlpha
• Sets up email domain: If external email server is configured (mailboxes, forwarding)
• Generates automatic SSL certificate: Orders and installs SSL if AutoSSL/Let's Encrypt is enabled
• Syncs report providers: Connects Google Analytics etc.
• Enables automatic backup: Activates backup schedule if configured for the plan
• Sends notifications: Notifies user and admins about successful import

Import Status Indicators

Each step can have one of the following statuses:

• Not Started (gray circle): Step hasn't been executed yet, waiting for previous steps
• In Progress (yellow/orange spinner): Step is currently being executed
• Completed (green checkmark): Step finished successfully without errors
• Failed (red alert icon): Step encountered an error and couldn't complete

When a step fails, the entire import is marked as failed, and you'll see:

• The specific step that failed highlighted in red
• Detailed error message describing what went wrong
• Step-specific error details in the Logs tab
• Suggested actions to resolve the issue
• Retry option to re-run the migration

Migration Process Flow

Automatic Migration (Plugin Method with Login):

Client initiates import → Enters WordPress URL → Provides WP admin credentials
→ PanelAlpha validates credentials → Selects service and options
→ PanelAlpha logs into WordPress → Installs migration plugin
→ Plugin analyzes source site → Downloads files and database
→ Uploads to destination → Extracts and imports data
→ Configures WordPress → Cleanup → Migration complete

Automatic Migration (Plugin Method - Manual Install):

Client initiates import → Enters WordPress URL → Downloads plugin ZIP
→ Client uploads plugin to WordPress → Activates plugin
→ Plugin connects to PanelAlpha → Selects service and options
→ Plugin analyzes source site → Downloads files and database
→ Uploads to destination → Extracts and imports data
→ Configures WordPress → Cleanup → Migration complete

Automatic Migration (FTP Method):

Client initiates import → Enters WordPress URL → Provides FTP credentials
→ PanelAlpha verifies FTP connection → Detects WordPress installation
→ Selects service and options → Downloads files via FTP
→ Downloads database via FTP → Uploads to destination
→ Extracts and imports data → Configures WordPress
→ Cleanup → Migration complete

Manual Migration:

Admin initiates migration → Selects user and service
→ Creates instance → Generates temporary FTP credentials
→ Admin uploads wordpress-files.zip and database.sql
→ Clicks Verify → PanelAlpha validates uploads
→ Clicks Continue Import → Extracts and imports data
→ Configures WordPress → Cleanup → Migration complete

Migrations in Progress

The main migrations table is divided into three tabs: In Progress, Failed, and Successful migrations.

The In Progress tab shows all currently running migrations, including both automatic (client-initiated) and manual (admin-initiated) migrations.

Table columns:

• ID Number: Unique migration identifier (also service ID); click to view service details page
• User: User who owns the instance; hover to see tooltip with user details (email, status), click to view user profile
• Service: Service/plan to which the WordPress installation is assigned; displays plan name
• Domain: Domain of the migrated WordPress installation; hover to see instance details tooltip
• Status: Current migration step and progress
  • Shows which step is currently executing (e.g., "Downloading Files...")
  • Displays alert icon (⚠️) if action is required
  • Shows progress percentage for applicable steps
  • Click the status or alert icon to open migration details

Available actions:

• Show Details (eye icon): Opens the Migration Details modal with full information about the migration
• Stop Migration (stop icon): Halts the migration immediately (only for automatic migrations)
  • Confirms before stopping
  • Migration will be marked as failed with reason "Stopped by admin"
  • Cannot stop manual migrations that are past the upload stage
• Delete (trash icon): Stops and removes the migration permanently
  • Confirms before deletion
  • Stops the migration process if running
  • Removes all migration records
  • Does NOT delete the partially created instance
• Bulk Delete: Select multiple migrations using checkboxes and use the mass actions dropdown

Status indicators:

• Green checkmark (✓): Step completed successfully
• Yellow/orange spinner (⟳): Step currently in progress
• Red alert (⚠️): Step failed or requires manual action
• Gray circle (○): Step not yet started

Taking Action on In-Progress Migrations

When a migration shows an alert status, it typically means:

1. Manual upload required: For manual migrations waiting for admin to upload files

   • Action: Upload wordpress-files.zip and database.sql via FTP
   • Next: Click Verify to check uploads, then Continue Import

2. Verification needed: Files uploaded but not yet verified

   • Action: Click the Verify button in Process Details
   • Next: If successful, Continue Import button will be enabled

3. Error occurred: A step failed during execution

   • Action: Review Logs tab for specific error message
   • Next: Retry migration or Mark as Failed

4. Admin intervention needed: Configuration or permission issue requires manual resolution

   • Action: Follow instructions in Process Details tab
   • Next: Contact hosting server admin if needed, then Retry

Migration Details

The Migration Details modal provides comprehensive information about a migration. Click "View Details" on any migration to open this modal.

The modal contains several tabs:

Steps Tab

Track the progress of each migration step. The table shows:

• Step Name: Descriptive name of the migration step
• Status: Visual indicator (checkmark, spinner, alert, or circle)
• Duration: Time taken to complete the step (for completed steps)
• Actions: Tooltip with detailed information about the step

Each step displays its current status:

• Completed steps are marked with a green checkmark and show completion time
• In-progress step shows yellow spinner with current action
• Failed steps show red alert icon with error summary
• Not started steps show gray circle

Click the info icon next to any step to see detailed description of what that step does.

Source Details Tab (Automatic Migrations Only)

Available only for automatic migrations initiated by clients. Shows connection information for the source WordPress:

• URL: The website address of the source WordPress installation
• Import Method: Type of migration (Plugin or FTP/SFTP)
• Protocol: Connection type (FTP, SFTP, or FTPS) - for FTP method only
• Path: Directory path to the WordPress installation on source server
• FTP Host: The FTP server address - for FTP method only
• FTP Port: The port number used for the connection - for FTP method only
• FTP Username: The FTP account username - for FTP method only
• FTP Password: The FTP account password (click eye icon to reveal) - for FTP method only

For plugin-based migrations, this tab shows:

• WordPress admin URL (if credentials were provided)
• Plugin installation method (automatic or manual)
• Plugin status and version

Note: Manual migrations do not have source details since files are uploaded directly by admins.

Process Details Tab

Provides instructions and connection details for the migration process. Content varies based on migration type and current step:

For Manual Migrations (during upload stage):

Shows FTP account details for uploading files:

• Remote Server Temporary Directory: Path where files should be uploaded
• FTP Host: The FTP server address (usually hosting server IP or hostname)
• FTP Port: The port number for FTP connection (default: 21)
• FTP Username: Temporary FTP account username
• FTP Password: Temporary FTP account password (click copy icon to copy)

Instructions displayed:

1. Connect to the FTP server using provided credentials
2. Upload wordpress-files.zip to the temporary directory
3. Upload database.sql (or database.sql.gz) to the temporary directory
4. Click the Verify button to confirm uploads
5. If verification succeeds, click Continue Import

Verification status:

• Not verified: Files not yet checked (Verify button enabled)
• Verifying: Currently checking uploaded files (spinner shown)
• Verified: Files found and valid (Continue Import button enabled)
• Failed: Files missing or invalid (error message with details shown)

For All Migrations (after upload stage):

Shows current migration progress and technical details:

• Current step being executed
• Files being processed
• Database import progress
• Any warnings or notices

Action buttons:

• Verify: Check if required files are uploaded (manual migrations only)
• Continue Import: Proceed with migration after verification (manual migrations only)
• Copy: Copy individual field values to clipboard (click icon next to each field)

Destination Details Tab

Contains information about the target location for the imported WordPress. This information is useful for troubleshooting and manual verification:

Server Information:

• Server IP/Hostname: The address of the destination hosting server
• Server Name: Name of the hosting server in PanelAlpha
• Control Panel: Type of control panel (cPanel, DirectAdmin, Plesk, etc.)

Hosting Account Information:

• Hosting Account Username: Username of the hosting account on destination server
• Hosting Account Main Domain: Primary domain associated with the hosting account
• Hosting Account Status: Account status (active, suspended, etc.)

WordPress Installation Details:

• Domain: Website domain for the imported WordPress
• Path: Directory path to the WordPress installation on destination server
• URL: Full URL where WordPress will be accessible
• PHP Version: PHP version configured for the instance

Database Information:

• Database Host: Address of the database server (usually localhost or specific hostname)
• Database Name: Name of the WordPress database created on destination
• Database User: MySQL user created for the WordPress database
• Database Password: Password for database access (click eye icon to reveal)

Additional Details:

• WordPress Version: Detected version of WordPress being migrated
• Instance ID: PanelAlpha instance ID for the imported site
• Created At: Timestamp when migration was initiated

Actions:

• Copy: Copy individual field values to clipboard (useful for troubleshooting)
• Test Database Connection: Verify database credentials are working (if migration failed during DB import)

Logs Tab

Provides detailed real-time log information about the import process, including all actions performed and any encountered errors.

Log Entry Components:

• Timestamp: Exact date and time of the log entry (e.g., "2026-01-28 14:32:15")
• Log Level: Type of log message
  • INFO (blue): Normal operation, step completion, progress updates
  • WARNING (yellow/orange): Non-critical issues, version mismatches, recommendations
  • ERROR (red): Critical errors that caused step or migration failure
  • DEBUG (gray): Technical details for advanced troubleshooting
• Step: Which migration step generated this log entry
• Message: Description of the action or error
• Details: Additional technical information (hover over message or click expand icon)

Common Log Messages:

Informational (INFO):

• "Import process started"
• "Step completed: Creating Domain"
• "WordPress files downloaded successfully (1.2 GB)"
• "Database imported: 45,234 records processed"
• "Import process completed successfully"

Warnings (WARNING):

• "Source WordPress version (6.2) differs from latest (6.4)"
• "Large file detected, splitting into chunks"
• "Deprecated plugin detected: [plugin-name]"
• "Database optimization recommended"

Errors (ERROR):

• "Cannot connect to FTP server: Connection refused"
• "Database import failed: Access denied for user"
• "File extraction failed: Insufficient disk space"
• "WordPress configuration error: wp-config.php not writable"

Using Logs for Troubleshooting:

1. Identify failed step: Look for ERROR entries to see which step failed
2. Review error message: Read the specific error that occurred
3. Check preceding entries: Review INFO/WARNING messages before the error
4. Look for patterns: Multiple timeouts might indicate network issues
5. Copy for support: Use copy button to share log excerpt with support team

Log Filtering:

• Filter by log level (ALL, INFO, WARNING, ERROR, DEBUG)
• Search logs by keyword
• Export logs to file for offline analysis

Auto-refresh: Logs update automatically in real-time for in-progress migrations (refreshes every 5 seconds).

Failed Migrations

The Failed Migrations tab lists all migrations that encountered errors and couldn't complete successfully.

Table columns:

• ID Number: Migration/service identifier; click to view service details
• User: User who owns the instance; hover for tooltip, click for user profile
• Service: Service/plan assignment
• Domain: Domain of the failed migration
• Status: Reason for migration failure (detailed error message)

Common failure reasons:

• "Stopped by admin": Admin manually stopped the migration
• "Cannot connect to FTP server": FTP credentials invalid or server unreachable
• "Cannot dump MySQL database on remote server": Database export failed on source
• "Insufficient disk space": Not enough space on destination server
• "WordPress not found at specified path": Invalid path provided for FTP method
• "Database import failed: Table already exists": Database collision on destination
• "File extraction failed": Corrupted ZIP file or permission issues
• "Connection timeout": Network connectivity issues during file transfer
• "Maximum execution time exceeded": PHP timeout during large data processing

Available actions:

1. Show Details (eye icon):

   • Opens Migration Details modal
   • Review Logs tab for specific error messages
   • Check which step failed
   • See source and destination details

2. Retry (refresh icon):

   • Re-initiates the WordPress instance migration
   • Starts from the beginning
   • Useful if failure was due to temporary issue (network, server load)
   • Only available for automatic migrations and manual migrations that failed after upload

3. Mark As Successful (checkmark icon):

   • Manually marks the migration as successful
   • Use when you've manually fixed the issue outside PanelAlpha
   • Migration moves to Successful tab
   • Instance status is updated to active
   • Important: Ensure you've actually completed the migration manually before using this

4. Delete (trash icon):

   • Permanently removes the migration record
   • Stops any retry attempts
   • Removes partial data if migration didn't complete
   • Confirms before deletion
   • Can bulk delete multiple failed migrations

Troubleshooting workflow:

1. Review failure reason: Check Status column for initial indication
2. Open details: Click Show Details to see full logs
3. Identify root cause: Read error messages in Logs tab
4. Attempt resolution:
   • For credential errors: Verify and retry with correct credentials
   • For space issues: Free up disk space on destination server
   • For timeout issues: Consider manual migration for large sites
   • For plugin errors: Try FTP method instead
5. Retry or manual completion: Use Retry if issue resolved, or complete manually and Mark As Successful

Successful Migrations

The Successful Migrations tab lists all migrations that completed without errors.

Table columns:

• ID Number: Migration/service identifier; click to view service details
• User: User who owns the instance; hover for tooltip, click for user profile
• Service: Service/plan the instance is assigned to
• Domain: Domain of the successfully migrated WordPress
• Status: Always shows "Completed" with green checkmark
• Completed At: Timestamp when migration finished

Available actions:

• Show Details (eye icon):
  • View complete migration information
  • Review Steps tab to see all completed steps
  • Check Destination Details for instance information
  • Review Logs for complete migration history
  • Useful for audit trails and verification

Information available in Details:

• All steps with completion times
• Total migration duration
• Source details (for automatic migrations)
• Destination server and database credentials
• Full log history

Use cases:

• Audit trail: Review who migrated what and when
• Documentation: Reference for setting up similar migrations
• Troubleshooting: Compare successful migration logs with failed ones
• Reporting: Export data for management reports
• Verification: Confirm all post-migration actions completed

Best Practices

For Automatic Migrations

1. Educate clients: Provide clear instructions on both import methods (plugin vs FTP)
2. Recommend plugin method: It's more reliable and user-friendly for most cases
3. Monitor regularly: Check In Progress tab daily for stuck migrations
4. Review failures: Investigate failed migrations to identify common issues
5. Document patterns: Note which types of sites/servers have issues

For Manual Migrations

1. Prepare files beforehand: Have clients prepare ZIP and SQL files before starting
2. Test file integrity: Verify ZIP and SQL files are not corrupted before uploading
3. Use compression: Compress database dumps with gzip for faster uploads
4. Verify immediately: Don't wait to verify uploads - do it right after upload completes
5. Monitor logs: Watch logs during Continue Import for any warnings

For Large Sites

1. Consider manual migration: More control for sites over 5GB
2. Split during off-hours: Schedule large migrations during low-traffic periods
3. Compress database: Use gzip compression for databases over 100MB
4. Check server resources: Ensure destination has adequate disk space and memory
5. Monitor progress: Keep Migration Details modal open to watch progress

Security Considerations

1. Temporary FTP accounts: Always removed automatically after migration
2. Credential storage: Source credentials not stored after migration completes
3. Sensitive data: Database passwords visible only to admins with appropriate privileges
4. Plugin cleanup: Migration plugin removed from source if auto-installed
5. Audit trail: All migrations logged for security review

Troubleshooting Common Issues

Migration Stuck on "Downloading Files"

Possible causes:

• Large file set (many files or large total size)
• Slow network connection to source server
• Source server throttling connections
• FTP connection timeout settings

Solutions:

• Wait longer - large sites can take hours
• Check source server logs for connection issues
• Try manual migration with pre-prepared ZIP file
• Consider splitting large sites into smaller chunks

"Cannot Connect to FTP Server"

Possible causes:

• Incorrect FTP credentials
• FTP server firewall blocking PanelAlpha
• Wrong FTP port specified
• FTP server down or maintenance

Solutions:

• Verify FTP credentials with separate FTP client
• Check source server firewall rules
• Try different port (21 for FTP, 22 for SFTP)
• Contact source hosting provider

"Database Import Failed"

Possible causes:

• Corrupted database dump
• MySQL version incompatibility
• Insufficient MySQL privileges
• Database too large for destination server limits

Solutions:

• Re-export database with different tool
• Check MySQL version compatibility (source vs destination)
• Verify database user has all privileges
• Increase MySQL max_allowed_packet setting
• Split large database imports

"WordPress Not Found"

Possible causes:

• Incorrect path specified
• WordPress installed in subdirectory
• Non-standard WordPress structure
• Files not readable by FTP user

Solutions:

• Verify exact path to WordPress installation
• Check for wp-config.php and wp-content in specified path
• Try common paths: /, /public_html, /public, /htdocs, /www
• Check FTP user has read permissions

Plugin Method Fails

Possible causes:

• WordPress admin credentials incorrect
• Security plugins blocking login attempts
• Two-factor authentication enabled
• WordPress in maintenance mode

Solutions:

• Verify admin username and password
• Temporarily disable security plugins
• Disable 2FA for migration duration
• Take WordPress out of maintenance mode
• Try manual plugin installation option

Additional Resources

• Client Area: Importing Existing Instance - Client-side import documentation
• Server Migration - Complete server migration guide
• Hosting Servers - Hosting server configuration
• Services - Managing services and plans