So, you find yourself in a need of a Sitecore upgrade and don’t know what to start with or how to approach it? This series of blog posts will cover the whole process from zero to hero, or in upgrade terms – from planning to going live. It comes in the form of a guide that will save you at least 2 times of cumulative effort, due to avoiding hidden traps and unobvious issues on your way to a shiny upgraded solution. Over time I have struggled and documented most of these issues and now want to share them all in one place.

Content

Part 1: Scope Planning
Part 2: Upgrade Tactics
Part 3: Content Migration
Part 4: Upgrading the Codebase
Part 5: Changes if Sitecore 10.x
Part 6: Testing and going live

Changes in Sitecore 10.x

In this post, I will take you through the important changes coming with Sitecore 10.x and how to make the transition to the latest releases of Sitecore smoother than ever.

1. Containers

Containers are immutable which means that any changes to the file system within the container will be lost as soon as the container restarts

When switching to containers your codebase will remain the same, however, there are minor changes – debugging now works a little bit differently: now we need to choose a relevant container and then pick up a process within it. instead of publishing artifacts into a webfolder we now build images and run a container from it.

With Docker, you no longer deploy just your application code. A container is now the unit of deployment, which includes the whole environment: OS and application dependencies. Therefore, your build process will have to be extended to build Docker containers and push them to a container registry.

Both Azure and AWS are suitable for running Sitecore in containers. They both provide managed Kubernetes services and other container hosting options.

Besides containers you need to consider other system components: SQL, Solr, and optionally Redis

Moving everything to containers will also require thinking through how you will monitor the health of each service. Luckily, Sitecore comes with health check endpoints (/healthz/live and /healthz/ready) out of the box, which you can use for this purpose.

Kubernetes on its own will impose quite a steep learning curve.

You can learn more tips on migrating your Sitecore solution to Docker.

2. Upgrade the database

Databases were not 100% compatible between the versions. Previously (before 10.1) one had to run an upgrade script against Core and Master in order to attach both to a vanilla target instance and progress with the rest of the upgrade.

The update script ensured the schema and default OOB content get updated by applying all the intermediate changes between both versions. This article explains in more detail how did we upgrade databases before 10.1.

The idea that came into consideration was that supplying empty databases with a vanilla platform would eliminate the above need for everyone who updates DB to operate at an SQL admin level. But every version has its own unique set of default OOB items, where do we keep them?

Because of container-first the way of thinking, there was a clear need to store those somewhere at a filesystem level, so it was a matter of choosing and adopting a suitable data provider. Protobuf from Google was a perfect choice ticking all the boxes, moreover, it is a very mature technology.

The diagram shows the difference in how we did the database upgrades before Sitecore version 10.1 and from 10.1 onwards

3. Items as Resources

With that in mind, now have a database full of content you can upgrade the version without even touching it. SQL Databases stay up to date, and the rest of the default content gets updated by just substituting Protobuf Data resource files.

Sitecore called this approach Items as Resources.

I would strongly recommend you look into the items as a resources plugin for the Sitecore CLI – instead of going through all the trouble of making asset images, you can create Protobuf files that contain all your items and bake them directly into your container image.

I wrote a comprehensive explanation about everything you wanted to ask about “Items-as-Resources” coming with the new Sitecore 10.1 – hope it answers most of your questions.

You can create your own resource files from *.item serialization using Sitecore CLI Items as Resources plugin (version of CLI 4.0 or newer). You cannot delete items from Resource File it is read-only, but this trick (by Jeroen De Groot) helps you “remove” items at the Provider level.

4. Sitecore UpdateApp

But how do we upgrade let’s say 8.2 databases to 10.3?

From 10.1 and onwards databases come with no content – it becomes a matter of removing the default items from the SQL database, leaving the rest of the content untouched. That default content would come from the actual items resource file which will be placed in App_DataItems folder.

For upgrading to Sitecore 10.1 with UpdateApp Tool it comes to purely replacing resource files which naturally fits into a container-filesystem way of doing business.

That is where a new tool comes into play, please welcome Sitecore UpdateApp Tool!

This tool updates the Core, Master, and Web databases of the Sitecore Experience Platform. You must download and use the version of the tool that is appropriate for the version and topology of the Sitecore Experience Platform that you are upgrading from. The versioning of UpdateTool itself in some way reflects the platform version you’re upgrading to – use UpdateApp 1.2.0 for upgrading to 10.2. and UpdateApp 1.3.1 if upgrading to 10.3..

This tool also works with official modules resource files for upgrading Core, Master, and Web databases (such as SXA, SPE, DEF, Horizon, both CRMs, etc.).

5. Asset images

To containerize modules we now use Sitecore Asset images, instead of packages as we did before. But why?

First of all, you won’t be able to install a package that drops DLL due to the instance bin folder being locked for an IIS user.

Secondly, containers are immutable and are assumed to be killed and instantiated – any changes to a container will go away with it.

Also, since a module is a logical unit of functionality with its own lifecycle and assets – it should be treated by the “works together, ships together” principle. Also, you as a package maintainer provide sample usage Dockerfiles for the required roles so that your users could pick them up with ease.

Sitecore Asset images are in fact storage of your module’s assets in the relevant folders, based on the smallest windows image – nanoserver. You can create those manually, as I show on this diagram.

With the recent platform, there are two ways of managing the items: either creating an Items Resource file or converting the package zip file into a WebDeploy package, then extracting its DACPAC file and placing it into the DB folder. In either case, the file structure will stay as pictured in the diagram above.

There is a tool called Docker Asset Image Creator that does exactly that – automates creating an asset image for a given Sitecore module (by Robbert Hock).

I would recommend going through these materials for a better understanding:

Installing Sitecore Packages to Containers (by George Chang)
Creating custom Sitecore images for modules
How to dockerize your Sitecore module (by Mihaly Arvai)

Overall, the changes in Sitecore 10.x when it comes to upgrading and using containers provide many benefits and can help make the process of upgrading Sitecore platforms more efficient and reliable. These changes demonstrate Sitecore’s commitment to constantly improving and evolving its platform, and they can help developers take advantage of the latest and most advanced features of Sitecore.

In the final chapter of this blog series, I will talk about the necessary activities one should take prior to going live, and immediately after it.