The
Sitecore® Experience Platform™ (XP) is the leading digital experience platform and it provides integrated end-to-end solution like native content management, omnichannel
headless delivery, customer-interaction and engagement data, and personalization and analytics, to build seamless digital experience for your end users.
Any product upgrade always provides the best solution with an advance set of technologies / tools, new capabilities, get the latest updates and fixes with mainstream support, and quality improvements.
To start with Sitecore Upgrade Process, we should have discussion with IT and Business on need of Sitecore upgrade, existing issues and other items which you can find in my previous
Sitecore Upgrade Process blog series.
This article describes how you can upgrade existing
Sitecore container based environment to latest version of Sitecore:
-
Go to the Installation and Upgrade Guides or Sitecore downloads site and download the latest Sitecore Version Container Deployment Package and Upgrade Container Deployment Guide
-
Go through the Sitecore Upgrade Container Deployment Guide (SC-XP-[Version Number]-Upgrade-Container-Deloyment-Guide-en.pdf)
-
Validate the Software requirements
-
Go through the release notes of latest Sitecore version
Prerequisites for upgrading
-
Backup the databases
-
Check the Prerequisites steps in the Sitecore Upgrade Container Deployment Guide
-
Download and extract the Sitecore Container Deployment package
-
The above Deployment package provides the Sitecore upgrade Docker Compose files and Sitecore Kubernetes specification files for each Sitecore topology:
Upgrade on-prem Sitecore Databases in Containers
-
In this article we will upgrade the Sitecore Docker Container XP1 topology, so go to the location SitecoreContainerDeployment.[Version Number]\compose\ltsc2019\upgrade\xp1 and open the upgrade.env file and understand the environment variables list for Sitecore upgrade container:
| Name |
Description |
Default Value |
|
COMPOSE_PROJECT_NAME
|
The name of the topology.
|
sitecore-xm(p)1
|
|
SITECORE_DOCKER_REGISTRY
|
The target registry.
|
scr.sitecore.com/sxp/
|
|
SITECORE_VERSION
|
The Sitecore version that you want to upgrade to.
|
10.3.X-[your Windows version] For example, 10.3.X-ltsc2019 or 10.3.X-2004
|
|
SQL_DATABASE_PREFIX
|
The prefix that is used to resolve the Sitecore database names.
|
Sitecore
|
|
SQL_SERVER
|
The SQL Server name. For more information about how to specify the connection strings for SQL Server, see Troubleshoot connecting to the SQL Server Database Engine
|
|
SQL_USERNAME
|
The SQL Server administrator username.
|
|
SQL_PASSWORD
|
The SQL administrator user password.
|
|
COMPOSE_PROJECT_NAME
|
The name of the topology.
|
sitecore-xm(p)1
|
|
IS_ALWAYS_ENCRYPTED
|
Whether Always Encrypted is configured for the databases to upgrade.
|
|
PROCESSING_ENGINE_TASKS_DATABASE_USERNAME
|
The name of the least privileged user that exists in the processing_engine_tasks database.
|
|
DATABASE_UPGRADE_FROM_VERSION
|
The Sitecore version from which you are going to upgrade the database
|
10.1.0
|
|
DATABASE_UPGRADE_TO_VERSION
|
The Sitecore version to which you are going to upgrade the database
|
10.3.0
|
|
SITECORE_LICENSE
|
The Sitecore license file converted to base 64 string through PowerShell script.
|
|
ISOLATION
|
Override for Docker isolation level Possible values: default, hyperv, process
|
default
|
|
Reference: Sitecore XP 10.3.0 Upgrade Container Deloyment Guide
|
-
I have used following values to upgrade Sitecore 10.1 Docker Container XP1 topology to Sitecore 10.3 Docker Container XP1 topology:
COMPOSE_PROJECT_NAME=amitkumar
SITECORE_DOCKER_REGISTRY=scr.sitecore.com/sxp/
SITECORE_VERSION=10.3-ltsc2019
SQL_DATABASE_PREFIX=Sitecore
SQL_SERVER=mssql
SQL_USERNAME=sa
SQL_PASSWORD=b
IS_ALWAYS_ENCRYPTED=
PROCESSING_ENGINE_TASKS_DATABASE_USERNAME=
DATABASE_UPGRADE_FROM_VERSION=10.1.0
DATABASE_UPGRADE_TO_VERSION=10.3.0
SITECORE_LICENSE=
ISOLATION=default
-
The value of SITECORE_LICENSE variable is compress and Base64 encode value of Sitecore license file. You can generate this value by passing the Sitecore license file path to function ConvertTo-CompressedBase64String (Appendix A – License file compression and encoding PowerShell helper function) mentioned in the Sitecore Upgrade Container Deployment Guide file.
The connection strings to databases:
-
To upgrade the Sitecore Docker Container, docker-compose.upgrade.yml contains the connection strings of the SQL databases that must be upgraded. You can take the connection strings from your docker-compose.yml or docker-compose.override.yml file based on your setup:
services:
mssql-upgrade:
image: ${SITECORE_DOCKER_REGISTRY}sitecore-xp1-mssql-upgrade:${SITECORE_VERSION}
environment:
IS_ALWAYS_ENCRYPTED: ${IS_ALWAYS_ENCRYPTED}
PROCESSING_ENGINE_TASKS_DATABASE_USERNAME: ${PROCESSING_ENGINE_TASKS_DATABASE_USERNAME}
Sitecore_ConnectionStrings_Core: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Core;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Master: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Master;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Web: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Web;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Experienceforms: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Experienceforms;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Processing_Engine_Tasks: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Processing.Engine.Tasks;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Messaging: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Messaging;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Reporting: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Reporting;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Xdb_Collection_Shard0: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Xdb.Collection.Shard0;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Xdb_Collection_Shard1: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Xdb.Collection.Shard1;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Sitecore_ConnectionStrings_Marketingautomation: Data Source=${SQL_SERVER};Initial Catalog=${SQL_DATABASE_PREFIX}.Marketingautomation;User ID=${SQL_USERNAME};Password=${SQL_PASSWORD}
Database_Upgrade_From_Version: ${DATABASE_UPGRADE_FROM_VERSION}
Database_Upgrade_To_Version: ${DATABASE_UPGRADE_TO_VERSION}
Sitecore_License: ${SITECORE_LICENSE}
isolation: ${ISOLATION}
If you are using any docker default network in your docker-compose files then you have to define the same network in the docker-compose.upgrade.yml otherwise upgrade process wouldn’t be able to connect with your SQL server databases and you will get the error:
ERROR: Executing 'C:\data\DatabaseUpgradeScripts\10.3.0\CMS_security.sql' file.
mssql-upgrade_1 | Invoke-Sqlcmd : A network-related or instance-specific error occurred while
mssql-upgrade_1 | establishing a connection to SQL Server. The server was not found or was not
mssql-upgrade_1 | accessible. Verify that the instance name is correct and that SQL Server is
mssql-upgrade_1 | configured to allow remote connections. (provider: Named Pipes Provider,
mssql-upgrade_1 | error: 40 - Could not open a connection to SQL Server)
Docker Compose Upgrade deployment:
-
Before execution of powershell scripts, you have to make sure that your Docker Desktop running in the Windows container mode
-
You will find compose-init.ps1 in the folder \compose\ltsc2019\upgrade\xp1. This powershell script will update the Sitecore upgrade environment file (upgrade.env) with required Sitecore 10.3 related environment variables and it’s not mandatory to execute this file because docker-compose file not using this
-
Good to place, required Sitecore upgrade files like upgrade.env, compose-init.ps1 and docker-compose.upgrade.yml in the same folder where the other normal Sitecore Docker Compose files present e.g. docker-compose.yml, etc..
├── docker-compose.yml
├── docker-compose.override.yml
├── init.ps1
├── .env
├── up.ps1
├── docker-compose.upgrade.yml
├── upgrade.env
└── compose-init.ps1
-
After adding required details to upgrade.env, compose-init.ps1 and docker-compose.upgrade.yml files, execute the following command to the RUNNING containers (your old Sitecore container setup should be running), to upgrade the Sitecore Docker Setup on your local system
docker-compose.exe -f .\docker-compose.upgrade.yml --env-file .\upgrade.env up
Docker Compose download the Sitecore upgrade container image from the Sitecore Container Registry and deploy this container to upgrade the SQL databases of your existing Sitecore XP installation.
When the upgrade process is completed, the upgrade container stops.
With the help of above Sitecore upgrade container changes, you can upgrade Sitecore XP and xConnect databases that are stored on-prem in containers.
Upgrade existing Sitecore Docker Container Setup Databases on Kubernetes
-
To upgrade the existing Sitecore Databases on Kubernetes you have to use the upgrade setup present at SitecoreContainerDeployment.[Version Number]\k8s\ltsc2019\upgrade\ based on your topology:
-
You can include this Kubernetes upgrade job into your build pipeline and execute once.
After successful completion of upgrade, you must delete the Kubernetes upgrade job.
Upgrade Sitecore Docker Container Setup
In the above sections, we learned how to upgrade the existing Sitecore databases which have historical data.
Generally, you will not setup the Sitecore containers from scratch on higher environment and you do the layering of any upgrade so previous steps will be helpful in those cases.
In case of local development setup, each developer has its own Sitecore instance on their system which they used for development and initial website structure (Sitecore Content Hierarchy) with all required templates or other items would be serialized.
If any new template or pre-requisite Sitecore Item e.g., common list should be committed in the repository and synced with the instance when the Docker instance is started.
On the higher environment generally initial sync required for whole content serialization, and after that you can sync only required Sitecore items, e.g., Sitecore templates or any Sitecore item list or Sitecore Rendering, etc.
These Sitecore serialized content would be deployed to Sitecore setup. In these cases, if you are planning to upgrade your Sitecore Container setup then you have to upgrade the Sitecore container setup (Sitecore Docker Compose and Docker Files) also and you don’t need to run the previous Sitecore Container Database upgrade step.
To upgrade your Sitecore Container solution:
-
Open the latest Sitecore Version Container Deployment Package downloaded in Upgrade Preparations section and open the XP1 topology:
The above setup will be plain vanilla Sitecore latest version Container setup and wouldn’t be having details about any modules.
-
If you are using Sitecore modules like CLI, SPE or Headless then better to take references of:
Sitecore/Sitecore.Demo.Edge:This repository is used for the primary Sitecore Edge for Content Hub and Experience Management
Sitecore/docker-examples
Update for Sitecore 10.3 ltsc2019 and ltsc2022 by AmitKumar-AK
Walkthrough: Setting up a development environment with the Sitecore Containers template for Next.js > sitecore.nextjs.gettingstarted project
-
The above GitHub repos will provide you the details of latest Sitecore Version Container setup.
-
Compare your .env file with plain vanilla Sitecore Container Setup and above GitHub repo .env files, and include the new/updated entries in terms of new parameters and updated values, e.g., Sitecore Version, Container images, etc..
-
Compare your docker-compose.yml file with plain vanilla Sitecore Container Setup and above GitHub repo docker-compose.yml files, and generally there will be new services or change in the image name and versions or new environment variables for services
-
Same way you have to compare the docker-compose.override.yml and Docker file for each role inside the docker\build folder:
-
In the docker setup, sometimes new folders need to be created to include new functionalities, e.g. Sitecore device detection etc.
And for this, details needs to be added in the docker-compose-override.yml in specific Sitecore Roles:
-
In Sitecore Docker Setup, you will be using the published Sitecore Container Images and different Sitecore Modules that are available as Docker asset images to build custom images and each image have tags with respect to Sitecore version, which needs to be validated during upgrade.
For example, in Sitecore 10.0.0-1809 you are using the Sitecore SXA Asset image sxa-xp1-assets with version 10.0.0-1809, so you have to find Sitecore SXA Asset image (version 10.3-1809) for Sitecore 10.3-ltsc2022 and for this you have to search in the official published images SITECORE-TAGS.md
The Sitecore SXA Asset image for version 10.0.0-1809 but not present for version 10.3-1809. In this case, you have to check the updated Sitecore Docker-Compose file for Sitecore SXA Asset image name and it’s mentioned as sitecore-sxa-xp1-assets instead of sxa-xp1-assets:
The same way, you have to validate all required Sitecore Container images for latest Sitecore Version by considering the details of different services at Sitecore Docker Compose file:
Once, you have updated all required Sitecore Container images for all Sitecore roles, then you have to execute the up script to build your newly upgraded Sitecore environment.
Speaking from past experience, you will have to execute up script many times to build the successful upgraded Sitecore Container environment 😊
Sitecore 10.3 Container Repository
Comments