Upgrading a Sitecore Helix Solution to Sitecore 10 and Docker

May 9, 2022

Sitecore has published Sitecore 10 Helix solutions to Github:

• https://github.com/Sitecore/Helix.Examples

There are 5 example solutions that show you how to setup Docker containers with Sitecore 10 whether you're using TDS, Unicorn, NextJS, or .Net Core. You can quickly build a solution and run a mostly vanilla Sitecore site locally or use it as a base for upgrading your own solution. This post describes how I used this as a basis for upgrading an existing Sitecore 9 Helix solution.

Preparing the Solution for Sitecore 10

I first upgraded each project's Sitecore nuget packages to the Sitecore 10.1 versions and removed any unused packages. I then changed each project's target framework to .Net 4.8. I finally looked through the other nuget references and upgraded GlassMapper, Coveo, and other dependencies to a compatible version.

After a trial build failed, I checked the web.config binding redirects and made sure they referenced the correct assembly versions. I downloaded the on-premesis Sitecore XM package and compared the web.config and references to our solution to ensure everything matched. The solution built successfully after that.

Sitecore 10 Helix Example

I proceeded to clone Sitecore's Helix.Examples project to a separate directory.

git clone https://github.com/Sitecore/Helix.Examples.git

Then I copied the following files and folders to my solution:

• /docker/ - entire directory
• /src/Environment/ - entire directory
• .dockerignore
• .env
• Directory.Build.targets
• Dockerfile
• Packages.props
• docker-compose.override.yml
• docker-compose.yml
• init.ps1

My main .sln file had to be updated to include the new project, Website. I also found it helpful to create a new folder in the solution named Configuration that included the new docker configuration files and web.config transforms.

The instructions on the Helix.Examples readme describe the minimum amount of configuration changes needed to load the sites. However, I preferred to adjust the .env, docker-compose.override.yml, and docker-compose.yml, and init.ps1 up front so that I could remove the BasicCompany boilerplate and prepare it for the multi-site solution that we have. It takes a bit of time to decipher but you can easily extend the yml to include new domains, settings, and applications.

For example, I didn't like the structure of the hostnames (ex. https://cd.basic-company.localhost) and wanted additional hostnames bound to the cd. So I added new parameters to the int.ps1 like:

$exHost = "example.docker.dev"

Then I made sure the additional hostnames were added to the host file with

Add-HostsEntry "example.docker.dev"

The .env file was updated with entries for the new hostnames like:

EX_HOST=example.docker.dev

Finally I bound the additional hostnames in the docker-compose-override.yml file with entries like:

labels:
    - "traefik.http.routers.cd-secure.rule=Host('CD_HOST') || Host('EX_HOST') || Host('EX2_HOST')

Building and Running the Containers

The Github solution has good instructions for getting started. Once you've initialized your environment and built the containers, you can access the website using the hostnames you configured.

Building a large solution with many unicorn files can be time consuming, but once built it can be turned on with docker-compose up -d and turned off with docker-compose stop.

Deploying Code Changes and Debugging

The new Website project contains a publish profile that publishes the solution build artifacts to the new /docker/deploy/ directory. This folder is watched by the CM and CD containers which will copy any new/changed files to the containers. The cycle of publish and reload is faster than it was for me when running the sites locally through IIS.

Furthermore, there is a Containers view in Visual studio that allows you to view the log stream, file system, and quickly launch a debugging session or interactive console.