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
Did this answer help? 0 People found this helpful (0 Votes)