Zoompf's Web Performance Blog

Note: Archived Content

This is the archived version of the Zoompf blog. Since our acquisition by Rigor, all our new research and posts on web performance are being published on The Rigor Blog

You Need A Website Migration Plan!

 Billy Hoffman on August 2, 2013. Category: Internal Development

This week we launched our newly redesigned site. To our visitors, this new site just magically appeared late on Friday, July 26th. However for us, there was weeks of work. And when it came time to launch, Mark insisted that we do something I had never done before: put together a migration plan.


At first, I didn’t think a migration plan was all that important. I mean, how hard can it be to move a new WordPress theme and some extra stuff from one system to another? However, I am convinced that creating a migration plan was one of the smartest things we did during the move. You absolutely should create and use a migration plan, regardless of how small you think the job is. In this post, I’ll explain why. I’ve also included the Zoompf website migration plan that we used to show you how detailed our plan was, and the steps we took, during our migration.

Simple Migrations Never Are Simple

Conceptually, migrating a new website on top of your old website should be simple. All you are doing is this:

  1. “Turn off” the old site.
  2. Copy over the new site.
  3. “Turn on” the new site.

However, this simple plan quickly grows. Migrations are always more complex than you think they are. For example, you need a backup in case you mess up. And what about that config file? So you start adding steps on to your simple process:

  1. Make a backup of the old site.
  2. “Turn off” the old site.
  3. Copy over the new site.
  4. Toggle some config file settings for the new site
  5. “Turn on” the new site.

Oh wait, we have a CMS! So when we do a “backup” what we really mean is “make an export of the database, AND make a copy of the webroot”. Also our PDFs are stored on a different hostname, so we need to make sure we grab them.

  1. Make a backup of the old site.
    1. Use SFTP to copy the webroot.
    2. Export a copy of the database
  2. “Turn off” the old site.
  3. Copy over the new site.
    1. SFTP the webroot
    2. Copy the PDFs from marketing’s system
  4. Toggle some config file for the new site
  5. “Turn on” the new site.

But wait! The new site is using different plugins, so we need to install those. And don’t we have do modify that logging script too? Crap! We forgot that .htaccess rule. Oh, wait, didn’t we change the URL for the product features? Won’t all the old blog posts hyperlink to the old page? We need to make sure our redirects are setup properly!

Do you see what I mean? Simple migrations grow in complexity. There are a ton of little things that have to be done. Backup this. Tweak that. Reset this. Copy that. And their order matters. If you forgot to backup something up at step 1, you are screwed if you try to do it at step 4!

Create your Migration Plan Ahead of Time

Since migrations can get complex you need to create a migration plan ahead of time, and write it down! The last thing you want to do is be in the middle of a migration and wondering what you need to do next. Sit down, write the plan out. Do this with someone else so you both identify all the steps involved and document the proper order!

Migration plans should include literally everything that you need to do to get the old site down, the new site up, and verify that everything is working properly. Every migration plan should have 5 sections:

  1. Preparing the new site
  2. Preparing the old site
  3. Migrating sites
  4. Testing
  5. Post migration steps

There will always be things that should be done to prepare both sites (backups at the very least). You will always have some migration tasks. You should always do rigorous testing when done. You will always have some steps once everything is done and tested (like having a party with the team).

To help, here is the Zoompf website migration plan Mark and I used when deploying our new website. Feel free to share it and use it as a basis for your next website migration.

It’s a Migration, not a Re-factor

The final thing to remember is that as you are migration a website don’t change to update or improve or change or refactor anything during the migration. If something needs to be improved, do it on the staging system and test it far before you migration the new website into your production environment! Now I know, I know: while you are migrating, you are going to notice something that your want to “fix” or “improve”. Don’t do that. Because then, if something doesn’t work, you don’t know if there was a problem with the migration, or a problem with your change. And then you are stuck, in the middle of the migration, probably with your website in a non-functional state, and you have to start debugging stuff. That is never fun.

Let me give you an example. As part of our Zoompf migration, I had to move some PHP files which are outside of the CMS theme or logic, which connect our website to our scanning servers for our Free Performance Report system. These PHP files are pretty old. They act as glue making requests to our scanning servers when verifying email addresses and initiating scan jobs. While porting them, I noticed buried down in the code was a hardcoded hostname in a URL that curl uses. It looked something like this:

$url = 'http://some-server.com/scanner/v2/?tix=' . $tix;

Even though that hostname was still the correct one, the programmer in my shouted: Abstract that out! So I replaced it with:

/*top of the file */
$ScannerHost = 'some-server.com';
... /*bunch of code */
$url = 'http://' + $ScannerHost + '/scanner/v2?tix=' . $tix;

I then proceeded to continue to copy over the files and do some configuration work. When it came time to do testing the free scan didn’t work. Crap! We messed up the migration! We reviewed our steps checked everything, and we could not figure out the problem. For the life of us, we had no idea why it broke. I must have looked at that PHP file for 30 minutes, doing various forms of printf-style debugging, before I found the problem. The + operator can’t be used for string concatenation! I write mostly in C# where you use + for both addition and string concatenation. However you have to use . in PHP to add strings together. My older code with the v2?tix=' . $tix; even use . properly!

I repeat: Don’t make unscheduled, unplanned, and more importantly, untested changes during your migration. If you see something that needs improvement, add that to your Post Migration Steps section of your plan. Remember, you should first focus on simply migrating a functional website from one system to another. Once you have completed that, and tested it, then you can make other changes.


Have some thoughts, a comment, or some feedback? Talk to us on Twitter @zoompf or use our contact us form.