This comprehensive guide walks you through the process of safely migrating your WHMCS installation to a new server, ensuring minimal downtime and maintaining data integrity. Whether you're moving to a new hosting provider or upgrading your server infrastructure, follow these steps for a successful migration.
Prerequisites
- Access to both source and destination servers
- PHP 8.1 or later installed on the destination server
- MySQL 5.7.8 or MariaDB 10.3.x or later
- Apache 2.4 or later with mod_rewrite enabled
- Valid WHMCS license
- Backup storage space at least 2x your current WHMCS installation size
Pre-Migration Preparation
1. Verify System Requirements
Ensure your new server meets these minimum specifications:
- Memory: 2GB RAM (4GB recommended)
- Storage: SSD recommended for optimal performance
- PHP Extensions: curl, gd, json, mysql, xml, zip
- Apache Modules: mod_rewrite, mod_ssl
2. Disable WHMCS Automation
Locate and disable all WHMCS-related cron jobs:
# List all cron jobs crontab -l # Edit cron jobs crontab -e # Comment out WHMCS cron entries by adding # at the start of each line # */5 * * * * /opt/cpanel/ea-php81/root/usr/bin/php -q /home/user/public_html/whmcs/crons/cron.php
Backup Process
1. Database Backup
# Using mysqldump (recommended method) mysqldump -u username -p whmcs_db > whmcs_backup.sql # Compress the backup gzip whmcs_backup.sql
2. Files Backup
# Create a compressed backup of WHMCS files tar -czf whmcs_files.tar.gz /path/to/whmcs
Migration Steps
1. Transfer Files
# Using rsync (recommended for large installations) rsync -avz --progress /path/to/whmcs user@newserver:/path/to/destination # Or using scp scp -r whmcs_files.tar.gz user@newserver:/path/to/destination
2. Database Restoration
# Create new database mysql -u root -p CREATE DATABASE new_whmcs_db; GRANT ALL PRIVILEGES ON new_whmcs_db.* TO 'whmcs_user'@'localhost'; FLUSH PRIVILEGES; exit; # Restore database gunzip < whmcs_backup.sql.gz | mysql -u username -p new_whmcs_db
3. Configuration Updates
Edit configuration.php with new database credentials:
# Secure copy of configuration file cp configuration.php configuration.php.bak # Edit configuration file nano configuration.php # Update these lines: $db_host = "localhost"; $db_username = "new_username"; $db_password = "new_password"; $db_name = "new_whmcs_db";
Post-Migration Tasks
1. Verify File Permissions
# Set correct permissions
find /path/to/whmcs -type f -exec chmod 644 {} \;
find /path/to/whmcs -type d -exec chmod 755 {} \;
chmod 777 /path/to/whmcs/templates_c/
chmod 777 /path/to/whmcs/downloads/
2. Restore Cron Jobs
# Add WHMCS cron jobs to new server */5 * * * * /opt/cpanel/ea-php81/root/usr/bin/php -q /path/to/whmcs/crons/cron.php */5 * * * * /opt/cpanel/ea-php81/root/usr/bin/php -q /path/to/whmcs/crons/pop.php
3. Update DNS and SSL
- Update DNS records to point to the new server IP
- Install SSL certificate on the new server
- Update WHMCS system URL in admin area
Common Issues and Solutions
Database Connection Errors
- Verify database credentials in configuration.php
- Check database user privileges
- Ensure MySQL service is running
License Validation Failures
- Reissue license through WHMCS client area
- Clear /templates_c directory
- Verify correct domain in configuration
Payment Gateway Issues
- Update callback URLs in gateway settings
- Verify SSL certificate installation
- Check firewall rules for gateway IPs
Security Considerations
- Remove backup files after successful migration
- Update admin directory location if necessary
- Implement IP whitelisting for admin access
- Enable two-factor authentication