I do all my WordPress upgrades manually.  I still get notifications of new versions, but they are not installed automatically.  This allows me to stage my upgrade, run backups, and generally ensure I can recover if anything happens.  Previous upgrades have always gone without a hitch, so I was not expecting any trouble from this one, but a minor change in my process resulted in an unnecessarily long down-time.

My upgrade process is fairly straightforward.  On my local development machine I keep a source controlled version of the site.  This version is my exact production site, with all my changes and customizations.  When a new version comes out, I copy it over my development site.  I can then inspect and merge all the modified files, giving me an updated version locally. 

Once I am satisfied with the changes, I verify the site still runs locally, and then commit my local version.  Next, I make a backup of my production database.  Since I keep copies of all my content locally, I am less concerned with losing data then I am with speed of recovery.  Having a fresh backup lets me instantly restore my state if the upgrade fails and I need to revert to the previous version.  Much easier than trying to manually reload everything.

Once I have committed my local site to source control and saved the database, I am ready to move my site onto my production server. In the past, I have simply taken the site off-line and made the upgrade.  This meant deleting the existing site and copying the upgraded version from my local machine via FTP.

This time, I decided to incorporate a technique I use on my other websites to minimize downtime.  Instead of taking the site off-line so I can delete the existing site, I install the new version in a new directory alongside the existing version.  When everything is ready, I simply point my server at the new directory, upgrade my database and I’m done.  I could also do something similar with my database to avoid any downtime at all, but WordPress generally works well with old databases and upgrades them really quickly.

Blank Website

Initially everything looked successful.  I switched the site over, jumped into the admin area to upgrade the database and jumped out to see how the new site was behaving.

The public website was blank.  Completely empty.  I tried restarting the server.  Nothing.

I jumped back into the admin area, and it was working fine.  Very odd.  My next thought was something is wrong with my theme, so I navigated to the theme area:

ERROR: The theme directory "twentyfifteen" does not exist.

That was very odd.  Mainly because I don’t use the “Twenty Fifteen” theme, so there was no reason for it to exist, but also because my theme was not listed at all.  I double checked my installation and verified that my theme existed.  I also uploaded a copy of the “Twenty Fifteen” to see if I could recover the site while tracking the problem down.

No luck.  My admin area still gave me the same error about “twentyfifteen” not existing.

At this point I was a little frustrated.  The site ran flawlessly locally – but for some reason returned a blank website on my production server.  I was tempted to simply revert back to my old version and call it a day, but I don’t like unsolved problems.

My next step was to disable all my plugins to verify that they were not causing problems, but when I went to the plugin section via my admin panel, it showed no plugins. 

So whatever the issue was affected both my themes and my plugins.  Just to be sure I renamed my plugin directory and checked again, but there was still no change.

That was when it hit me.  My wp_config.php file defines the location of several directories relative to my website.  It occurred to me that since I had a custom directory structure, it may still be pointing at my old site. 

Sure enough, both the WP_CONTENT_DIR and the WPCACHEHOME variables were pointing to my old site.  Once I updated them to point to my new site the blank screen went away and everything started working again.

So now I need to ensure my local machine uses the same directory names as my production server to ensure that no other path issues crop up for future deploys.