There are many parts to the full life-cycle of a Sitecore solution and one that often gets ignored or de-prioritized is the upgrade process. Like other pieces of software available on the market today, Sitecore comes with a built-in update/upgrade mechanism. Ok, let’s be real, its not like WordPress’s one-click, 10 second, upgrade. The Sitecore upgrade process is certainly involved, but definitely doable. The key to continuing to leverage all of the new features and enhancements of Sitecore is to have an upgrade strategy in place and keep on the upgrade path. This post is an examination of various things to consider when doing an upgrade and more specifically, a roadmap for upgrading across many versions.
Determine Your Version Jump Points
First, in order to know how you’re going to do your upgrade, you need to determine your current version, and your target version. Sitecore upgrades from version-to-version often allow you to upgrade from each major release to the next, but not skip major releases. For this reason, you need to map out your plan. For example, I recently upgraded a solution from 6.1 to 6.3.1 (latest recommended release). I will use my recent upgrade as an example here. The process involved:
- Go to the download page for the target version (6.3.1)
- In the upgrade section, find the prerequisite version and take note of it and the download page URL (in this case, 6.3.0 rev. 100716+)
- Following the same pattern, go to the prerequisite version of the version you just note
- Continue this process until you determine each version you need to upgrade to, in reverse order
- Once you find all versions you need until you’re current version is within the prerequisites, you can start to plan your upgrade process
For me, upgrading from 6.1 to 6.3.1 involved these version jump points:
- 6.1 – original version
- 6.2 (initial release)
- 6.3 (initial release)
- 6.3.1 – target version
Prepare Everything Up Front
Now its time to prepare everything you can up front. Seasoned developers know that it takes a lot of up front planning and discovery before actual development can occur on a project. This can help plan out tasks and break the larger process into smaller manageable chunks. The same thing is true with the upgrade process. Each version jump is a pivotal milestone in the process, so let’s first prep everything up front.
First, create a spreadsheet or some tabular way to track the versions. Next, create some dummy folders on your file system for each version of the site. Yes, this sounds tedious, but you want to maintain the integrity of the site from start to finish, and having the separate incremental jump versions will help you with QA and in the case of a disaster. You’ll probably want something like this for a file system:
- c:\inetpub\wwwroot\mysite (this is the original)
Now that you have empty site roots, create new websites in IIS, one for each version. Again, this probably sounds tedious, but it will really help in the long run with identifying problems areas and overall QA. In your spreadsheet, for each version you listed, list the respective wwwroot folder, and the hostname in IIS. For me, I used the following hostnames:
Also, you should have been saving or bookmarking the various Sitecore download pages for each version along the way. Put in the links for these versions in your spreadsheet for fast access to exactly what you’re working on.
While we’re keeping track of everything, go ahead and list out the database for each site as well. Many Sitecore upgrades cause database changes so its best to have unique sets. First plan out the names using a version naming convention to keep the groups together, e.g.
This is what your spreadsheet could look like:
(click for full-size)
Upgrade in Segments
Now that all prep is done, its time to start the upgrade process. First copy your original site into the next version’s folder (e.g. copy into c:\inetpub\wwwroot\mysite_620). I highly recommend you use a free program such as TeraCopy to copy the files at fast speeds. Seriously consider TeraCopy, it will really copy much faster than Windows. Leave the other dummy version folders alone at this point. To save some time, delete any temp files you can from your site before you do the transfer. This will make your copy operation leaner.
In addition to copying over version-specific files, you need to backup the databases and create new versions of them. Backup the initial version’s databases (core, master, web — no extra module databases) and create new ones with a similar version naming convention. The database names should be in your spreadsheet, so its a matter of copying and pasting the names you listed.
Update the configs for your newly copied files. Once your files are copied over to the new site, make sure you update the
dataFolder path in the
web.config and update the IIS site root to the “website” folder. Also update the
ConnectionStrings.config to use the newly duplicated databases. Make sure your site runs at the new hostname (e.g. mysite_620). At this point it’s still running the former version of Sitecore, despite the hostname.
Now go to the SDN download page for the version your upgrading to (the link should be in your spreadsheet). Don’t do anything except read the upgrade directions. Once done, re-read the upgrade directions. Download the update pseudo-package (it ends in .update) and any other files for the upgrade, like .sql files. Follow the directions and do your upgrade.
If at any point in the upgrade you get a .NET error about permissions, its likely due to the process that’s running the site trying to replace Sitecore DLLs. This is ironic because Sitecore its literally trying to replace itself. You’ll end up with a clash and get a .NET error. Don’t worry. Just go to your site root’s “temp” folder (e.g. c:\inetpub\wwwroot\mysite_620\website\temp). In here find the most recent Upgrade folder (marked by the version number and timestamp). In that folder run the
process.bat batch file which will overwrite the DLLs with the new ones. Try our your site now and it should work.
Repeat the Pattern
Now repeat this same process for the next version. Copy the site root from this newly upgraded version to the next with TeraCopy again. Also remember to do the database backup again but backup from the newest databases. Again, the database names should be listed in your spreadsheet. Update the
dataFolder and connection strings again and do it all over again. Continue this process until you’ve reached your target version.
Note: Not all upgrades are the same in both effort and timing. Some may be fast while others will require extra work, like updating database schemas.
QA Across Jump Points
Now that you’ve finished the process of upgrading take a break — it’s probably been a few hours. Now it’s time to QA the site. Errr, I mean sites. For every jump site you’ve created, you need to QA. Seriously. I recommend you look at all of your pages for each version you’ve created and ensure everything is consistent across all. Also test out the Sitecore interface and page editor if you use it. If you find any pages that break you can determine which version jump caused this break by having each site to review. For example, I found a major issue on a site going from 6.2 to 6.3. I received parser errors on a multi-line text field. That led to the 6.3 documentation and release note which revealed that the
FieldRenderer had some changes with break tags and new line characters. Having all versions of the site allowed for an instant understanding of which version upgrade caused the issue. There can be a variety of other issues that arise, such as dynamic stylesheets in the rich text editor breaking, so really take advantage of having a site for each version to QA.
If you follow the detailed directions above, you’ll be able to manage a potentially overwhelming process by breaking it down into separate tasks. As with all things a developer does, take each piece at a time, in this case a version upgrade. Separating out all of the versions will give you better visibility into what versions could cause issues on your site. They also serve as checkpoints. If one of the later upgrades fails you don’t have to start at the very beginning. You can also more consistently QA your site across every single version change to understand at what points things change with the Sitecore API and/or the Sitecore interface.