WordPress migration to a new server

From time to time a WordPress site needs to be migrated to a new server. Here’s the basic procedure. The forest, if you will.

Moving WordPress is the official solution for those who need to move from one server to another. It’s pretty thorough and easy to follow.

Moving WordPress Multisite is a more surgical procedure to be followed when working with a Multisite installation. The procedure provided here will work with Multisite but administrators should carefully review the official doc before moving forward. One especially nice reference in the doc is to the DB Search and Replace Tool, a php program that can be used to make the url substitutions described below.

The basic prerequisites?

1. A mysqldump to text of the installation database. Check wp-config.php for the database name, location, user and password. Keep this info close at hand, you’ll need it.

2. A backup archive (preferably tar.gz, because it preserves file creation dates and permissions) of the installation.

3. Users and groups whose IDs show up on the existing server should be re-created on the new server, unless you’ve already got a plan to accomodate that.

4. All php and mysql packages installed on the existing server need to be on the new server, again unless you know you don’t need one or more of them.

5. Make sure software versions are at least at the same level or newer than on the existing server.

Now for the procedure:

1. If you’re not changing the url for the site:

a. Re-create the site database for the site and its database users on the new server.

b. Set permissions as they were in the old database.

c. If you don’t know the admin user password for the site, change it in the database dump text to the md5 hashed string of your choosing (see this post for how to generate that string.

d. Import the database dump into the new database.

e. Unarchive the file system backup to the location where the site will live on the new server.

f. Verify that filesystem permissions are correct (your web server user needs to have read access to wp-config.php and read and write access to everything under wp-content). You don’t have to put the files in the same exact path as on the original server, or give the same users access to it, but make sure that any hardcoded paths in wp-config.php and the other files match what you end up with. For example:

find . -name "*.*" -type f | xargs grep -i 'C:\'

The above comes in especially useful when moving sites from Windows to Linux servers (something I encourage wholeheartedly).

g. Verify that the db name, username and password in wp-config.php match whatever you set in the database (you can use different values so long as you make sure that the db and wp-config.php match).

2. If you are changing the url for the site you need to perform a couple of extra steps.

b. Check all configuration files, most importantly wp-config.php and .htaccess, to make sure that any references to the old url get changed to the new. Do this manually.

c. Check all files under wp-content, for references to the old url and do a search and replace with find and perl:

cd wp-content
find . -name "*.php" -type f -exec perl -pi -e 's/oldsite.example.com/newsite.example.com/g' {} \;
find . -name "*.css" -type f -exec perl -pi -e 's/oldsite.example.com/newsite.example.com/g' {} \;

d. After importing the database, install Interconnect IT’s Search and Replace DB script in the root of the WordPress installation directory for the new site:

wget https://www.interconnectit.com/wp-content/uploads/2011/05/searchreplacedb21.zip
unzip searchreplacedb21.zip

Then run the script from a web browser:


Follow the prompts to import the db connect info from wp-config.php.

Leave the “preserve GUIDs” checkbox unchecked.

Make sure all tables are highlighted.

Enter in the values for one search and replace pair at a time.

For example:

Search: oldsite.example.com Replace: newsite.example.com

In addition to the site url, you should also do a search and replace for the old and new hosts. WordPress records the FDQN for its host whenever an ftp operation is performed through it (for example, when installing plugins).