DevOps

Migrating Magento 2 to a New Server

Migrating a Magento 2 store to a new server is a critical operation that demands precision. Whether you are upgrading your infrastructure, moving to a cloud provider like AWS or DigitalOcean, or switching hosting partners, downtime must be minimized. A failed migration can lead to lost orders, broken customer sessions, and a tarnished reputation.

This comprehensive guide covers the technical execution of a "zero-downtime" migration strategy using the rsync utility and database replication techniques. We assume you have root access to both the source and destination servers.

Phase 1: Server Prerequisites & Preparation

Before moving a single byte of data, the destination server must be configured effectively identical to the source. Magento 2 is sensitive to environment configurations.

1. Software Stack Matching

Ensure the following versions match exactly:

  • PHP Version: If Source is 8.1, Destination must be 8.1. Check enabled modules with php -m.
  • MySQL/MariaDB: Version mismatches (e.g., 5.7 to 8.0) can cause syntax errors in dumps.
  • Elasticsearch/OpenSearch: Required for catalog search functioning.
  • Varnish: If used, ensure the VCL configuration matches.

2. User & Group Setup

Magento requires a specific file system owner (usually named magento or www-data). Do not run your store as root.

# On Destination Server useradd -m -U -r -d /home/magento magento usermod -aG www-data magento chmod 755 /home/magento

3. SSH Key Exchange

To allow seamless rsync transfers without password prompts, copy the public SSH key from the Destination server to the Source server's authorized_keys.

Phase 2: The Initial Data Sync (While Live)

The secret to low downtime is performing the bulk of the transfer while the current site remains live and taking orders. We used rsync for this as it is resume-able and efficient.

Syncing the File System

Run this command from the Destination server. We exclude var/cache, var/log, and node_modules to save time.

rsync -avzP \ --exclude 'var/cache' \ --exclude 'var/page_cache' \ --exclude 'var/session' \ --exclude 'var/log' \ --exclude 'node_modules' \ user@source-server-ip:/var/www/html/ /var/www/html/

Flags explained: -a (archive mode, preserves permissions), -v (verbose), -z (compress during transfer), -P (show progress and allow resume).

Phase 3: The Database Dump & Switch

This is the only phase where maintenance mode is required. Plan this for your lowest traffic window (e.g., Sunday 2 AM).

1. Enable Maintenance Mode

Stop new orders from coming in to prevent data disparity.

bin/magento maintenance:enable

2. Dump the Database

Using mysqldump with compression is standard practice. For larger databases (>5GB), consider using n98-magerun2 db:dump --compression=gzip.

mysqldump -u user -p database_name | gzip > db_backup.sql.gz

3. Final File Delta Sync

While the database was dumping, new product images or session files might have been created. Run the rsync command from Phase 2 one last time. It will be very fast as it only copies changed files.

4. Import & Configure on Destination

Import the database and update the configuration file.

# Import zcat db_backup.sql.gz | mysql -u user -p new_database_name # Update env.php nano app/etc/env.php # Update 'host', 'dbname', 'username', 'password' arrays

Phase 4: Permissions & DNS Switch

Fixing Ownership & Permissions

Incorrect permissions are the #1 cause of "500 Internal Server Errors" after migration. Reset them explicitly.

chown -R magento:www-data /var/www/html/ find . -type f -exec chmod 644 {} \; find . -type d -exec chmod 755 {} \; chmod +x bin/magento

DNS TTL Strategy

24 hours before migration, lower your DNS TTL (Time To Live) to 300 seconds (5 minutes). This ensures that when you update the A Record to the new server IP, the change propagates globally almost instantly.

Troubleshooting Common Issues

Error: 500 Internal Server Error

Usually permissions. Check var/log/system.log. Often caused by .htaccess syntax errors if moving from Apache 2.2 to 2.4.

Error: Styles Missing (Broken Layout)

Static content failed to generate. Run bin/magento setup:static-content:deploy -f and clear Varnish.

Conclusion

Server migration is risk-management. By following this protocol—matching environments, syncing data while live, and managing DNS TTL—you can achieve a near-zero downtime switchover.