Migrating Your WordPress Site to Platform i Manually with rsync

For large or busy websites, a manual transfer is the most reliable way to ensure that your migration is successful. In this guide, we’ll focus on using the command line, using the rsync protocol. Remote synchronization using rsync has a few major advantages including the ability to easily resume interrupted transfers, and quickly re-sync any files that have changed. This guide will also feature using WP-CLI over SSH, a convenient way to manipulate WordPress websites from a remote terminal.

Throughout this guide, we’ll use the terms Origin site and Destination site to refer to your old hosting provider to your new site on Platform InMotion.

Prepare the Origin Website for Migration

There are several things you should do to get ready for your transfer ahead of time, including some housekeeping and maintenance tasks that often fall through the cracks on any live website. Check out our Ultimate Guide to WordPress Site Migration for a detailed list of things to prepare for during a website transfer.

As always when performing a major operation on your website, you should make sure that you have a backup of your website. 

Set up SSH Keys for Access from Server to Server

First, follow these instructions to add an SSH key to your Platform i VPS and log into your server. Now, we’ll set up a separate key that you’ll use to communicate between the origin server and the destination server.

1. Log into your Platform i VPS via SSH, and switch to the wordpress user.
   su - wordpress
2. Create the .ssh directory and generate a new SSH key. 
3. Follow the interactive prompts to name the key and add a passphrase to ensure the security of your new key.
   mkdir -p ~/.ssh && cd ~/.ssh/ && ssh-keygen
4. In this example, the new key is named transfer_key for clarity’s sake. If you name your key something different, replace the name of the key in the following commands in this guide.
5. Run the following command to print your public key:
   cat transfer_key.pub
6. Copy the public key, and add it to your Origin Server‘s authorized keys. This step will depend on your hosting provider, so check their documentation if you’re not sure. Here’s a guide on adding the key using cPanel.
7. Once it’s added, test the connection with a command similar to the following, substituting your origin user and server for username@example.com:
   ssh -i ~/.ssh/transfer_key username@example.com

Configure SSH to use Origin Server Easily

Next, we’ll set up a simple configuration file to make our lives easier for the rest of the process. Enter the command nano ~/.ssh/config and enter the following values for your origin server:

 Host origin
      	User username
        HostName 111.222.121.212
        IdentityFile ~/.ssh/transfer_key
        Port 22

Substitute your User, origin server host name or IP address, and Port number for the values above. Type ctrl-x, y, and enter. You may need to set the correct permissions for the config, using the command:
chmod 600 config

Now, you’ll be able to simply use the command ssh origin instead of typing out the path to the key, username, and server hostname.

[wordpress@vps##### .ssh]$ ssh origin
Enter passphrase for key '/home/wordpress/.ssh/transfer_key': 
Last login: Fri Nov  3 11:10:49 2023 from vps#####.inmotionhosting.com
user@example.com [~]#

Using WP-CLI Over SSH to Connect to Your Origin Server

Let’s gather some information about your origin website that we’ll need later in the migration process. Use the following command to get your Database Table Prefix:

[wordpress@vps##### ~]$ wp --ssh=origin --path=public_html --version
Enter passphrase for key '/home/wordpress/.ssh/transfer_key': 
WP-CLI 2.8.1
[wordpress@vps##### ~]$ wp --ssh=origin --path=public_html config get table_prefix
Enter passphrase for key '/home/wordpress/.ssh/transfer_key': 
wp_

In this example, the table_prefix value is the default wp_ but yours may differ. If that’s the case, be sure to make a note of it.

Put the Origin Site into Maintenance Mode

This step is optional, but you may want to place your origin site into maintenance mode to prevent any changes during the database export. Use the following command, or use one of the popular maintenance mode plugins available on the WordPress Repository.

[wordpress@vps##### ~]$ wp --ssh=origin --path=public_html maintenance-mode activate
Enter passphrase for key '/home/wordpress/.ssh/transfer_key': 
Enabling Maintenance mode...
Success: Activated Maintenance mode.

Exporting and Copying the Database with scp

Next, we’ll export the database and transfer it to our destination server using the scp command. In this example, we’re naming the database export file transfer_db.sql to make sure it’s easy to remember.

[wordpress@vps##### ~]$ wp --ssh=origin --path=public_html db export transfer_db.sql
Enter passphrase for key '/home/wordpress/.ssh/transfer_key': 
Success: Exported to 'transfer_db.sql'.
[wordpress@vps##### ~]$ scp origin:transfer_db.sql ./
Enter passphrase for key '/home/wordpress/.ssh/transfer_key': 
stdin: is not a tty
transfer_db.sql                               100%  327KB  25.3MB/s   00:00 
[wordpress@vps##### ~]$ ls
cloud-apps  doc_root  logs  transfer_db.sql

Back up Your Existing Site on the Destination Server

It’s a good idea to back up your existing site on the destination server, even if it’s merely a fresh WordPress installation, because it has your existing database credentials, database options, and .htaccess rules.

[wordpress@vps##### ~]$ cp -r doc_root doc_root.bak
[wordpress@vps##### ~]$ ls
cloud-apps  doc_root  doc_root.bak  logs  transfer_db.sql
[wordpress@vps##### ~]$ wp --path=doc_root db export ./doc_root.bak/backup_db.sql
Success: Exported to './doc_root.bak/backup_db.sql'.
[wordpress@vps##### ~]$ 

Save your Connection Credentials for Platform i

This step is optional, but if you’d like to preserve the connection credentials to Platform i and restore them to your transferred database, use the following commands. If you prefer, you can allow Platform i to repair the connection automatically after the transfer.

[wordpress@vps##### ~]$ wp --path=doc_root option get bg_connect_configs --format=json >> bg_connect_configs.json
[wordpress@vps##### ~]$ wp --path=doc_root option get central_connect --format=json >> central_connect.json
[wordpress@vps##### ~]$ wp --path=doc_root option get boldgrid_api_key --format=json >> boldgrid_api_key.json

Transfer Your Origin Site Files to the Destination Server with rsync

Next, let’s proceed with transferring your site files to the destination server. In this example, we’re excluding the wp-config.php file to maintain the database connection to the site. If you have important directives in your origin site’s wp-config.php, it’s recommended to set them up after performing the transfer.

[wordpress@vps##### ~]$ rsync -azv --exclude wp-config.php origin:public_html/ ./doc_root

Since we use d the -v option, you’ll see the files begin to transfer over listed as they progress. If this process is interrupted, you can simply repeat the same command and the sync will resume without overwriting the files that have already been transferred.

Import the Database to the Destination Server

First, we’ll clean the existing database with the following command. This is a destructive command, be sure you have a backup of the database from the previous steps.

[wordpress@vps##### ~]$ wp --path=doc_root db clean

Next, execute the command to import your database.

[wordpress@vps##### ~]$ wp --path=doc_root db import ./transfer_db.sql 
Success: Imported from './transfer_db.sql'.

Now, since we set the origin site into maintenance mode before exporting its database, we’ll need to deactivate maintenance mode after the import.

[wordpress@vps##### ~]$ wp --path=doc_root maintenance-mode deactivate

If your origin site had a different table_prefix than the default wp_, you’ll also need to set that. Replace ‘wp_’ in the following command with your table prefix.

[wordpress@vps##### ~]$ wp --path=doc_root config set 'table_prefix' 'wp_'

The next command may be optional, but to be safe we’ll run a script provided by your UltraStack VPS to ensure that all the file permissions are correct.

[wordpress@vps##### doc_root]$ fixperms wordpress

Restore the Platform i Connection Credentials

If you followed the optional step to save the connection credentials, you can restore them now with the following commands. Afterwards, install and activate the Central Connect plugin if your origin site didn’t already have it installed.

[wordpress@vps##### ~]$ wp --path=doc_root option update bg_connect_configs --format=json < bg_connect_configs.json
Success: Updated 'bg_connect_configs' option
[wordpress@vps##### ~]$ wp --path=doc_root option update central_connect --format=json < central_connect.json
Success: Updated 'central_connect' option
[wordpress@vps##### ~]$ wp --path=doc_root option update boldgrid_api_key --format=json < boldgrid_api_key.json
Success: Updated 'boldgrid_api_key' option
[wordpress@vps##### ~]$ wp --path=doc_root plugin install central-connect --activate

Use the Platform i Dashboard to Set the SiteURL

This step will differ depending on whether you plan to immediately update your site’s DNS to point to your destination server. If you are, follow the steps in this guide to add your domain and use the Site URL tool to set your site up on the correct domain.

If you want to test the site before transferring your DNS, which is recommended, follow these steps.

1. Log into Platform i and navigate to the project you’re working on.
2. Navigate to the Site URL tool, and select the Original Hostname from the drop-down list
3. Click Continue, then Apply
   

This process will take care of replacing your internal links so that you can thoroughly test the site.

Repair the Connection to Platform i

Once you’ve set the Site URL, you’ll likely still see a connection error in your Platform i Dashboard. If you skipped the step to restore the Connection Credentials, click Fix it For Me to install, activate, and configure the Central Connect plugin.

Common Troubleshooting for Transferred Sites

If you’re experiencing any problems with your newly transferred site, here are a few common things to check.

Issues with Transferred .htaccess Rules

Issues with .htaccess may present symptoms like 404 errors, 403 errors, or 500 errors. Check your transferred .htaccess file for directives that may have been set by cPanel or your origin host. Commonly, you can simply replace your .htaccess file with the one you backed up earlier.

[wordpress@vps##### ~]$ cp doc_root.bak/.htaccess doc_root/.htaccess

PHP settings

You may have transferred over a php.ini or user.ini file from your origin server that may cause issues. You can troubleshoot these by simply moving the file to another name to check if the symptoms are resolved.

[wordpress@vps##### ~]$ mv doc_root/php.ini doc_root/php.ini.bak

Conclusion

Using rsync is a powerful way to transfer WordPress sites because it is very fast, stable, and easily resumable if the connection is interrupted. Be sure to check out our Ultimate Guide to WordPress Migration for many other ways to transfer your website. Congratulations, you’ve now transferred your site to Platform InMotion!