The Complete Guide to Migrating an instance of WordPress
Hi Folks. I’ve been learning and tinkering with WordPress for quite some time now and it’s been quite an adventure to say the least. This very web site is a WordPress theme believe it or not. One downfall that any new WordPress developer will run into is: How do I move this code to a different environment and get it to work?
In my initial google searches on the topic I was surprised to find that there was not a guide published anywhere that had all of the necessary steps. Most of the helpful tutorials that I could find only contained fragments of the process and I was left scratching my head, wondering… Ok I did all that.. now why doesn’t it load?
Please bear in mind that this guide is meant to give the reader all of the steps that apply to cross platform migration. Configuring XAMP or MAMP and all of the steps involved with that process is outside of the scope of this tutorial. I use MAMP as a local development environment. Let’s begin:
The steps are essentially the same whether you are moving a local development instance of Wordpess to a web server, or an instance from a web server to your localhost. You have to copy ALL of the code files contained in your installation directory to the new host. More often than not, I am performing this set of tasks to move an existing instance / theme into my local development environment to pimp it out or build plugins for it etc.
To begin, just fire up your favorite FTP application (I use FileZilla) and login to the host. If you’re a hardcore CLI ninja then you can just SCP the installation directory UP or DOWN. Once logged in, navigate to your public_html (www) directory and copy the code files to that directory. In MAMP the default public directory for the apache server is /Applications/MAMP/htdocs/. In MOST web servers the default public facing directory on port 80 is public_html/. Depending on your level of knowledge and how few handcuffs your host puts on you, you can set the public directory to anywhere you like and name it anything you like. For the sake of this tutorial we will be putting our migrated wordpress installation in a directory called ../wordpressunicorns
A standard bare wordpress installation directory looks like this:
NOW that you have the code in the appropriate location (public_html/wordpressunicorns/) you have to get the database migrated AND connected. In case you didn’t know anything about wordpress – it’s a database driven web application that runs on PHP/MySQL so… those two servers have to be installed and running for it to work – but I’m going to go ahead and assume you already knew that and had that taken care of.
There’s 2 ways that you can migrate the database. The first, most common, and most accessible is to use phpMyAdmin which is typically installed on most shared web hosts. So let’s export the WordPress database! First log into phpMyAdmin (doing this can be different for different web hosts) There’s a few different versions of phpMyAdmin in use out there. More and more the major web hosts have upgraded to version 184.108.40.206 but if you’re still running version 220.127.116.11 (which ships with MAMP free) the steps are a ‘little bit’ different. Let’s assume you’re accessing your MySQL database via phpMyAdmin v. 18.104.22.168. First you have to select the database you want to export in the list by clicking on it:
That takes you to the Database Nav screen. Then you want to click the Export button:
Here’s where that whole Pesky version thing comes in. In earlier versions of phpMyAdmin the next screen presents you with a plethora of radio options and check boxes where you can tweak how the .SQL query text will be written. In the newer version you don’t see all of that unless you choose the “Custom — display all possible options,” radio. In my experience changing extended inserts and BLOB settings really doesn’t matter when you’re moving a simple wordpress installation. It may if you were migrating across different versions of MySQL but that, again is outside of the scope of this tutorial. In my recent experience, using the most up-to-date version of phpMyAdmin, choosing the “Quick Export,” option works just fine. So go ahead and choose it, and click the GO button. This downloads a text file with a .SQL extension to your local machine. This is essentially just a very long query that will create all the necessary tables and rows in a freshly minted mySQL database. Know where your browser downloads folder is because you’re going to need this file in a minute.
The next step in this process is to be sure we have a blank database for our WordPress tables to live in. Doing this is a bit different depending on your environment. For example, if you’re in a CPanel based shared hosting environment, you create MySQL databases and assign Privileges to them from the CPanel control panel. In a CPanel based environment you control INSERTS, DROPS, UPDATE anything data related via phpMyAdmin or the MySQL command line. CPanel doesn’t like for you to do things your way so you have to be aware of these little differences. If you’re a Linux Nerd like me you’ve written your own httpd conf file and you will either handle everything MySQL related from the command line, or all within phpMyAdmin. The standalone version of phpMyAdmin can create databases. Let’s assume you are running phpMyAdmin in MAMP or XAMPP — from the HOME screen — create a new database and name it whatever you like. For the sake of this tutorial we shall name our database wordpress_unicorns.
Once you click the magical “Create,” button a blank database is birthed. Next you will simply select the wordpress_unicorns database from the list as we did before and choose the “Import,” button instead of the “Export” button. Then Choose the .SQL file we created earlier from our export from your explorer or finder or whatever thing you use to find files on your computer machine. Then scroll down and click GO — This will import your database tables from the WordPress instance into the WordPress Unicorns database.
Now — you’re ALMOST THERE. If you copied any .htaccess files from your old environment you probably want to rename them to something like .htaccess.old until you have a chance to rewrite any rules there that may be screwing with your instance’s ability to load content in the new environment. The only 2 other things to consider are 1.) the wp-config.php file which contains global PHP variables that WordPress uses to store the data for connecting to the database (User Name, Password etc.) 2.) Row 1 and 37 in the wp_options table MUST be set to the new URL for the instance to load anything properly. Now just a second ago I mentioned the Database User Name / Password which is important. In the root directory of the wordpress installation (public_html/wordpressunicorns) there is a file called wp-config.php. That file was created during the wordpress installation. The user is prompted to enter the host, username, and password for the MySQL database. That data is then written to the file. I find that it’s easier for others if I DON’T change anything in the wp-config.php file. That way if the site ever gets moved back (or Git Pushed in my case) the wp-config.php file does not need to be changed or ignored by a repository for the site to work. I prefer to Create a user in my new environment with a username and password that matches what is in the existing file. You have to be sure to grant this user permissions to INSERT, UPDATE etc.. in the wordpress_unicorns database. So Fire up your favorite code editor (mine is sKedit) and check the wp-config.php file for the info that you need. In the example below we see the database name (DB_NAME) is ‘wordpress_unicorns’ (we’re already good there) we see that the database user name (DB_USER) is ‘Unicorn_Master’, and the database password (DB_PASSWORD) is ‘Unic0rnF4rT’.
Now we can go create that user in phpMyAdmin and GRANT it full privileges on the wordpress_unicorns database. First we Select wordpress_unicorns in the list nav on the left at the phpMyAdmin Home screen. Once you’re into the database Select Privileges and then Add New User :
At this next screen you simply fill out the text fields with the data you harvested from your wp-config.php file.
— then SCROOOLLL down and click the check all button to grant the user all privileges on the wordpress_unicorns database:
The final step to getting this up and running is to change the options in row 1 and 37 of the wp-options table which tells wordpress where it’s HOME URL is.. to do this navigate to the wp-options table and click the edit button for row 1:
We need to change that option_value colum for row 1 to be the correct URL — if you’re working in MAMP it may be http://localhost:8888/wordpressunicorns or something like that. We must repeat this step for row 37 which is on page 2 in the list of rows for wp-options:
THAT’S IT!!! It should now load when you navigate your browser to the appropriate URL. Now I’m going to be completely honest there are an infinite number of environmental variables to consider and knowing how to handle those curveballs takes a lot of experience and reading. I just wanted to publish a complete list of steps that will work in most typical environments. This tutorial should work for most people and at least give a running start for others who have other variables to consider. If it works — Time for a Beer (as in free).
Check back for more.