Upgrading Sitecore Docker Example Custom Images to Sitecore 10.4.0: A Step-by-Step Guide

👋Introduction

Sitecore 10.4.0 is the latest iteration of the popular digital experience platform, offering enhanced features and performance improvements. If you're using the Sitecore Docker Example Custom Images GitHub repository, upgrading to Sitecore 10.4.0 is essential to leverage the latest capabilities. In this article, we'll walk you through the process of upgrading your custom images to Sitecore 10.4.0, which support both targeting Long-Term Servicing Channel (LTSC) versions 2019 and 2022.

💡Understand the Repository Structure

The Sitecore/docker-examples/custom-images repository offers a sample Sitecore Docker Container setup codebase that can help you get started with your project.

The custom-images setup is useful for customizing the Sitecore Docker Container setup according to your project requirements and provides the setup for

1. Sitecore XP Single (XP0) topology

2. Sitecore XM Scaled (XM1) topology

3. Sitecore XP Scaled (XP1) topology

With the Sitecore Container Setup for Sitecore 10.4.0, you can gain hands-on experience with the Sitecore Docker Container Setup (including SXA).

You can review the Sitecore Container Environment setup details at Set up the Sitecore Container Environment before starting development with the Sitecore Docker Container. 🔝

⚙Sitecore Upgrade Process

To begin the Sitecore Upgrade Process, we should discuss the following high-level items with both IT and Business teams:

• What is the need of Sitecore Upgrade?

• What are the existing issues?

• Are there any performance and security improvements in newer versions which impacting our Business and Maintenance of existing Sitecore implementation?

• What is the expectation from Sitecore Upgrade from Business side?

You can find more details about the Sitecore Upgrade Process here: 🔝

👷‍♂️Changes done on Sitecore Docker Examples GitHub Repo for Sitecore 10.4.0

In this article, we'll focus on the steps and issues involved in upgrading the Sitecore Custom Docker image setup.

This upgrade process uses:

Upgrading Sitecore Docker Example Custom Images to Sitecore 10.4.0 with target OS versions LTSC2019 and LTSC2022 involves several steps. Here's a simple breakdown:

📝Prerequisites

Before initiating the upgrade process, ensure you have: 🔝

• Sitecore Docker Example Custom Images GitHub repository cloned locally

• Docker installed on your machine

• Familiarity with Docker and Sitecore architecture

🕹Updates

• In the custom-images/.env file update the following items:

SITECORE_VERSION=10.4.0
SPE_VERSION=7.0-1809
SXA_VERSION=10.4.0-1809
EXTERNAL_IMAGE_TAG_SUFFIX=ltsc2022

• In the custom-images/Packages.props update the following items:

    <PlatformVersion>10.4.0</PlatformVersion>
  

• In the custom-images/docker-compose.xm1.override.yml update the following items: 🔝

    BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}redis:3.2.100
  

• In the custom-images/docker-compose.xm1.yml update the following items:

    image: ${SITECORE_DOCKER_REGISTRY}redis:3.2.100
    image: ${SITECORE_DOCKER_REGISTRY}nonproduction/mssql-developer:2022
    image: ${SITECORE_DOCKER_REGISTRY}nonproduction/solr:8.11.2
  

• In the custom-images/docker-compose.xp1.override.yml update the following items:

    BASE_IMAGE: ${SITECORE_DOCKER_REGISTRY}redis:3.2.100
  

• In the custom-images/docker-compose.xp1.yml update the following items:

    image: ${SITECORE_DOCKER_REGISTRY}nonproduction/mssql-developer:2022
    image: ${SITECORE_DOCKER_REGISTRY}nonproduction/solr:8.11.2
  

• In the custom-images/src/DockerExamples.XConnect/App_Data/Models/DockerExamples.XConnect.Model.DemoModel, 1.0.json update the following items: 🔝

    "Version": "10.4"
  

• Run the initialization script init.ps1 by following the instructions provided here.

• Execute the clean-install.ps1 by following the instructions provided here.

⚠Setup Error

I encountered the following error when I executed the clean-install.ps1 script.

Incompatible OS Version

The host machine OS version was 22H2 (OS Build 19045.4170 or 10.0.19045), and I was trying to use the target OS version LTSC2022 images. This resulted in the following error: 🔝

Creating network "docker-examples_default" with the default driver
Pulling mssql (scr.sitecore.com/sxp/nonproduction/mssql-developer:2022-ltsc2022)...
2022-ltsc2022: Pulling from sxp/nonproduction/mssql-developer
ERROR: a Windows version 10.0.20348-based image is incompatible with a 10.0.19045 host

To fix the issue, I chose images that work with both LTSC2019 and LTSC2022 because the host OS version is 22H2 (OS Build 19045.4170 or 10.0.19045), which doesn't support the Windows version 10.0.20348-based image.

Volume name is too short

After fixing the previous error, I started getting this new error:

ERROR: for docker-examples_id_1  Cannot create container for service id: create .: volume name is too short, names should be at least two alphanumeric characters
Creating docker-examples_cortexreporting_1  ... error
ERROR: for docker-examples_cortexprocessing_1  Cannot create container for service cortexprocessing: create .: volume name is too short, names should be at least two alphanumeric characters
Creating docker-examples_xdbautomationrpt_1 ... error                                                                    is too short, names should be at least two alphanumeric characters
ERROR: for docker-examples_xdbautomationrpt_1  Cannot create container for service xdbautomationrpt: create .: volume naCreating docker-examples_xdbrefdata_1       ... error
ERROR: for docker-examples_xdbrefdata_1  Cannot create container for service xdbrefdata: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: for xdbcollection  Cannot create container for service xdbcollection: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: for id  Cannot create container for service id: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: for cortexprocessing  Cannot create container for service cortexprocessing: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: for cortexreporting  Cannot create container for service cortexreporting: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: for xdbautomationrpt  Cannot create container for service xdbautomationrpt: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: for xdbrefdata  Cannot create container for service xdbrefdata: create .: volume name is too short, names should be at least two alphanumeric characters
ERROR: Encountered errors while bringing up the project.
***Setup completed successfully***

To fix this issue, I ran the init.ps1 script with the needed parameters.

XConnect Web Application Error

After fixing the previous error, I started getting this new error: 🔝

2024-07-23 01:09:04.573 +01:00 [Error] XConnect Web Application Error: "System.ApplicationException: Exception trying to initialize Service Collection and Provider for WebAPI Dependency Resolver, Inner Exception: Unknown referenced model ('{
  \"Name\": \"Sitecore.XConnect.Collection.Model\",
  \"Version\": \"10.3\"
}') ---> Sitecore.XConnect.Schema.XdbModelParserException: Unknown referenced model ('{
  \"Name\": \"Sitecore.XConnect.Collection.Model\",
  \"Version\": \"10.3\"
}')
   at Sitecore.XConnect.Serialization.XdbModelReader.ParseModelReference(JToken value)
   at System.Linq.Enumerable.WhereSelectEnumerableIterator`2.MoveNext()
   at System.Collections.Generic.List`1.InsertRange(Int32 index, IEnumerable`1 collection)
   at Sitecore.XConnect.Serialization.XdbModelReader.Read()
   at Sitecore.XConnect.Serialization.XdbModelReader.Deserialize(String json, IXdbModelResolver knownModels, IXdbModelClrTypeLoader typeLoader)
   at Sitecore.XConnect.Web.Infrastructure.FileBasedXdbModelResolver.Load(String path)
   at Sitecore.XConnect.Web.Infrastructure.FileBasedXdbModelResolver.LoadModels()
   at Sitecore.XConnect.Web.WebExtensions.UseXConnectModel(IServiceCollection services)
   at Sitecore.XConnect.DependencyInjection.ServiceCollectionExtensions.GetXConnectServiceConfiguration(IServiceCollection services)
   at Sitecore.XConnect.Web.Host.WebApiConfig.ConfigureServices(HttpConfiguration config)
   --- End of inner exception stack trace ---
   at Sitecore.XConnect.Web.Host.WebApiConfig.ConfigureServices(HttpConfiguration config)
   at System.Web.Http.GlobalConfiguration.Configure(Action`1 configurationCallback)
   at Sitecore.XConnect.Web.Global.Application_Start(Object sender, EventArgs e)"

To fix this issue, I updated the Sitecore version to 10.4.0 at custom-images\src\DockerExamples.XConnect\App_Data\Models\DockerExamples.XConnect.Model.DemoModel, 1.0.json.

Data at the root level is invalid

After fixing the previous error, I started getting this new error:

Exception: System.TypeInitializationException
Message: The type initializer for 'Sitecore.SecurityModel.License.LicenseManager' threw an exception.
Source: Sitecore.Kernel
   at Sitecore.SecurityModel.License.LicenseWatcher.Created(String filePath)
Nested Exception
Exception: System.Xml.XmlException
Message: Data at the root level is invalid. Line 1, position 18551.
Source: System.Xml
   at System.Xml.XmlTextReaderImpl.Throw(Exception e)
   at System.Xml.XmlTextReaderImpl.ParseRootLevelWhitespace()
   at System.Xml.XmlTextReaderImpl.ParseDocumentContent()
   at System.Xml.XmlLoader.LoadDocSequence(XmlDocument parentDoc)
   at System.Xml.XmlDocument.Load(XmlReader reader)
   at System.Xml.XmlDocument.LoadXml(String xml)
   at ?????????????????????????????????????????.?????????????????????????????????????????(????????????????????????????????????????? , String )
   at ?????????????????????????????????????????..ctor(String )
   at ?????????????????????????????????????????..ctor(String )
   at Sitecore.Nexus.Licensing.NexusLicenseApi.get_Api()
   at Sitecore.Nexus.Licensing.NexusLicenseApi.GetSnapShot(Guid instance)
   at Sitecore.SecurityModel.License.LicenseManager.GetSnapshotData(Guid instance)
   at Sitecore.SecurityModel.License.LicenseManager.UpdateSnapshot()
   at Sitecore.SecurityModel.License.LicenseManager..cctor()

1508 01:52:18 INFO  License file created: c:\license\license.xml
1508 01:52:18 ERROR Error in LicenseWatcher
Exception: System.TypeInitializationException
Message: The type initializer for 'Sitecore.SecurityModel.License.LicenseManager' threw an exception.
Source: Sitecore.Kernel
   at Sitecore.SecurityModel.License.LicenseWatcher.Created(String filePath)
Nested Exception
Exception: System.Xml.XmlException
Message: Data at the root level is invalid. Line 1, position 18551.
Source: System.Xml
   at System.Xml.XmlTextReaderImpl.Throw(Exception e)
   at System.Xml.XmlTextReaderImpl.ParseRootLevelWhitespace()
   at System.Xml.XmlTextReaderImpl.ParseDocumentContent()
   at System.Xml.XmlLoader.LoadDocSequence(XmlDocument parentDoc)
   at System.Xml.XmlDocument.Load(XmlReader reader)
   at System.Xml.XmlDocument.LoadXml(String xml)
   at ?????????????????????????????????????????.?????????????????????????????????????????(????????????????????????????????????????? , String )
   at ?????????????????????????????????????????..ctor(String )
   at ?????????????????????????????????????????..ctor(String )
   at Sitecore.Nexus.Licensing.NexusLicenseApi.get_Api()
   at Sitecore.Nexus.Licensing.NexusLicenseApi.GetSnapShot(Guid instance)
   at Sitecore.SecurityModel.License.LicenseManager.GetSnapshotData(Guid instance)
   at Sitecore.SecurityModel.License.LicenseManager.UpdateSnapshot()
   at Sitecore.SecurityModel.License.LicenseManager..cctor()

To fix this issue, I clear the value of the SITECORE_LICENSE environment variable in the .env file. 🔝

Could not find file

After fixing the previous error, I started getting this new error:

2024-07-23 07:51:52.907 +01:00 [Error] XConnect Web Application Error: "System.ApplicationException: Exception trying to initialize Service Collection and Provider for WebAPI Dependency Resolver, Inner Exception: Could not find file 'c:\license\license.xml'. ---> System.IO.FileNotFoundException: Could not find file 'c:\license\license.xml'.
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize, FileOptions options, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.StreamReader..ctor(String path, Encoding encoding, Boolean detectEncodingFromByteOrderMarks, Int32 bufferSize, Boolean checkHost)
   at System.IO.File.InternalReadAllText(String path, Encoding encoding, Boolean checkHost)
   at ?????????????????????????????????????????.?????????????????????????????????????????(????????????????????????????????????????? , String )
   at ?????????????????????????????????????????..ctor(String )
   at ?????????????????????????????????????????..ctor(String )
   at Sitecore.XConnect.Configuration.Extensions.InitializeLicenseCheck(IServiceCollection collection, String licenseFileOrXml)
   at Sitecore.XConnect.Configuration.Extensions.UseXConnectServiceInitializationConfiguration(IServiceCollection collection, IConfiguration configuration, String[] configurationSectionNames, String initializationSectionName, Boolean validateConfiguration)
   at Sitecore.XConnect.Web.Host.WebApiConfig.ConfigureServices(HttpConfiguration config)
   --- End of inner exception stack trace ---
   at Sitecore.XConnect.Web.Host.WebApiConfig.ConfigureServices(HttpConfiguration config)
   at System.Web.Http.GlobalConfiguration.Configure(Action`1 configurationCallback)
   at Sitecore.XConnect.Web.Global.Application_Start(Object sender, EventArgs e)"

To fix this issue, I verified the Sitecore license and found that it had expired, so I updated it with an active Sitecore license.

✅Setup Validation

After all prerequisites, if you run the Sitecore Container Setup for any of the Sitecore Topologies by following the execution details, your Sitecore 10.4.0 CMS will be up and running with the Sitecore Experience Accelerator (SXA): 🔝

Sitecore XP Scaled (XP1) topology

Container Details

Sitecore XM Scaled (XM1) topology

Container Details🔝

🔦Conclusion

Upgrading your Sitecore Docker Example Custom Images to Sitecore 10.4.0 with target OS versions LTSC2019 or LTSC2022 is straightforward. By following these steps, you can take advantage of the latest features and performance improvements offered by Sitecore 10.4.0. Remember to test your upgrade thoroughly to ensure a smooth transition. 🔝

GitHub Repo for Sitecore Docker Example Custom Images 10.4.0

Target OS LTSC2029 and LTSC2022

This setup is based on:

Target OS LTSC2022

This setup is based on:

🙏Credit/References

🏓Pingback