The Sitecore upgrade process

Recently, I completed what is probably my 20th Sitecore upgrade project. Through those experiences, I’ve learned a lot about the process of doing an upgrade and challenges of those types of projects. Outlined below is a general description of the different phases of a Sitecore upgrade.

Phases of an upgrade

• Planning
• Initiating a code freeze
• Database backups and local restore
• The actual upgrade process
• Creating new infrastructure
• Setting up builds and releases
• Data transfer strategies
• Testing and Go Live

Planning

Before any work is done, the project is planned. The Sitecore environment and solution is evaluated to determine what needs to get changed and get a sense of the general level of complexity in a solution. Questions like the following might be asked:

• What Sitecore Modules are used and are they compatible with the version of Sitecore we are moving to?
• What search functionality is being used and can that continue to be used in the new version?
• How is xDB used and what does that mean for refactoring to be compatible with xConnect?
• Are any other Sitecore products used like EXM that would require an upgrade as well?
• What sorts of integrations are there and what’s the likely hood that an upgrade would cause an issue with them?
• How complex and organized is the solution itself? Will it be difficult to refactor?

In addition to the Sitecore and code solution questions, we also need to determine hosting requirements.

• Will the site be hosted on prem?
• If not, who is the hosting provider?
• If it’s Azure, will we be using IaaS or Paas? (IaaS is VMs in the cloud)
  • In the future, this question will also ask about Containers.
• What search provider will be used, Solr on VMs via Zookeeper or SearchStax. Will Coveo be introduced into the solution or is it already part of it?

After those questions are answered, we can then prepare a timeline for the project and arrange the work that comes next.

Initiating a code freeze

Generally there is a code freeze that happens during an upgrade project. A code freeze happens because during an upgrade, the code solution is also being upgraded. It might be possible to move some files between 2 versions of the solutions if small bugs were being fixed, but the code merge has to be done carefully. In general, I like to pause work on the old branch of code to avoid issues and uncertainty during testing the newly updated solution. Newly merged-in code from an old version of the solution may cause bugs in the new solution and could be difficult to track down during upgrade testing. It’s best to keep it simple while doing an upgrade.

Database backups and local restore

The developers will be provided a copy of the old versions database and setup the environment locally. They will verify and test that the solution is running locally just as it’s running in the production environment.

The actual upgrade process

Sitecore provides documentation on how to upgrade old versions of Sitecore to newer ones. This step must be followed to the letter. Moving from hop to hop or using the Express Migration Tool, whichever is allowed by Sitecore, the databases are updated with new items from packages provided by Sitecore, old incompatible modules are removed or updated, and new sql statements are run to change the database schema. The solution is then upgraded, by referencing the new dll versions of Sitecore that correspond to the version you are upgrading to. Once this is complete, the process of fixing errors begins and continues until the developer deems the site to be working satisfactorily locally.

Creating New Infrastructure

There needs to be a new solution for infrastructure when doing an upgrade. The old (current) site still needs to be up and running and still needs to be able to be deployed-to if a hotfix is required. This means it’s infrastructure and it’s build and release process cannot be changed.

Decision are made during planning on how what type of infrastructure will be used (IaaS, PaaS, On Prem VMs or engaging with Sitecore Managed Cloud to host the solution is a possibility. After the new environments are provisioned, new release pipelines are created to enable CI/CD to the environments.

Setting up builds and releases

This step is straightforward. The solution/code needs to be stored in a code repository. The build process checks the code out from the that repo and builds the solution per the build instructions. The outputs of the build are then used in the release.

A release takes the latest build artifacts and prepares them for the environment they are getting deployed to. It will swap in environment specific configurations and actually move the files to the destination environment server or app service. These releases get configured for each environment and each server in each environment that requires a deployment.

Data Transfer Strategies

When environments are setup using either VMs or App Services, the base Sitecore installation is also setup. This includes provisioning all the databases that are required to run the Sitecore platform. If you recall, the developers are upgrading a copy of the old production databases. This version of the database is the one being tested and verified.

There are 2 options you have to move data from the local developers machine to the dev, qa, and production environments.

1. Take a backup of the database on the developers machine and move that backup to the different environments.
   • The pros of this approach is that there is no other technologies you have to rely on to move the data. Database backups have been used for years and they are tried and true. Every upgrade I have ever done has used a database backup to move data from the developer machine to the environments and they have all been extremely successful. Those in favor of data syncs might say that it’s bad practice, however it was the only practice available since the existence of Sitecore prior to tools like Razl. Proponents of syncing might go as far as trying to scare you into thinking this is going to somehow ruin your installation. It won’t. Test first on your local. Test in your dev environment. While unlikely that you’ve modified your schema, if you have double check that against the ootb Sitecore database for the version you are moving to. Clean up the Sitecore event tables and properties tables (be careful if you’re using Coveo as they use the properties tables) and you’ll be ok.
   • TEST! TEST! TEST! You need to test on your local first. It’s not a risk if you test on your locals, and verify Sitecore is working correctly before you move the data. The developer should essentially run through the UAT test plan locally before the data and solution are deployed to the dev, staging, and production environments.
   • Once it’s up, you continue to move updates to the environments via packages. The only other time you will do a database restore is when doing the final upgrade.
2. Syncing Data
   • An alternative to backing up the database is to sync the data. That is, you setup a tool like Razl, Unicorn Sync, or https://github.com/michaellwest/Spe-Content-Migrator.
   • It takes a long time and uses a server to server approach, not database to database, so, if the application pool recycles on either side or something else taxes either system, the Sync process will either stop or slow to a crawl.   You have to terminate it and start over.
   • Since Razl depends on a server to server approach, it will also depend on how fast the servers are.  So, when we try to do this on a system that is under “powered” like in dev, uat, and prod before go live, it can go really slow.  The faster the servers, the faster the processing.  Systems, such as dev, aren’t usually perf tuned at the time we need the data up there.  We need the data to know how the system is performing, so data should be moved prior to perf tuning.   So,  Razl will likely not perform. 
   • Using a system like this to move data introduces risk.  Razl isn’t perfect and we’ve seen first hand through this process where items didn’t make it to the destination when we expected them to.  That means we have to spend time figuring out what Razl doesn’t like or what failed even though Sitecore is fine with it.  It’s messy and not 100% and can be a big time sink.

The thing about upgrades is that they are time sensitive. We don’t want the upgrade to go on longer than it needs to, especially when we enter the content freeze phase. If it takes you 3 days to successfully sync content to dev, and then another 3 to staging, and another 3 to production, when it could have taken 3 hours via a database backup, it’s pretty clear the route we should take. Let’s move on to the final phase.

Testing and Go Live

After the data has been moved to the new environments, testing will start. The client team will begin running through their test scripts and your QA team will as well. Bugs are found, fixed, new deployments happen and items packaged and installed. In the end, when UAT is complete and the application is approved and load tested, we are ready for go live.

Go live in this case consists of just a few steps generally but varys depending on the solution. We will keep it simple for our discussion here:

1. UAT is complete and the solution is signed off on in the production environment.
2. The client will enter into a content freeze on their “old” site.
3. A backup of the core and master database from the old site is taken. This backup is given to the developer to upgrade again. Same procedure as was done during the development phase. Following the Sitecore guide, schema changes are installed, new packages and items installed, etc.
4. Developer tests the upgraded database on the local environment.
5. The databases are then moved to the dev, staging, and production environments.
6. A full site publish is initiated to move content from the master to the web database.
7. Indexes in all 3 environments are rebuilt.
8. All 3 environments are smoke tested.
9. Go live by switching DNS to the new environment.

Summary

Each upgrade takes on a different flavor. Solutions and Sitecore Configurations vary in complexity and that complexity is what determines how long or the actual steps that need to occur during an upgrade. One thing about an upgrade is for sure, they are a ton of fun to work on. Happy Sitecoring!