Upgrade Sitecore CLI and Docker
In the previous post, we covered some of the gotchas with upgrading Sitecore CLI and how the Management Service may have dependencies that current projects may have dependencies on (for example, NuGet packages). If that post was missed, read more about it here. For Sitecore CLI to work, the correct version of Management Service must be installed.
This post will cover more on dealing with the Management Service module installed on the Sitecore container with Docker.
Sitecore modules are managed with Dockerfile
. For Management Services, two places define how the Docker image for the module is brought in and apply it to your Sitecore container.
MANAGEMENT_SERVICES_IMAGE=scr.sitecore.com/sxp/modules/sitecore-management-services-xm1-assets:4.1.0-1809
.env
ARG MANAGEMENT_SERVICES_IMAGE
FROM ${MANAGEMENT_SERVICES_IMAGE} AS management_services
# Copy the Sitecore Management Services Module
COPY --from=management_services C:\module\cm\content C:\inetpub\wwwroot
Dockerfile
Additional information about how to set up your Sitecore modules with Docker can be found here: https://doc.sitecore.com/xp/en/developers/102/developer-tools/add-sitecore-modules.html
This example will refer to CM
container. This stands for the Content Management instance running under Docker. If Docker runs a Sitecore container configured for a Standalone role, target that container for these changes.
In the environment variable in the example above, the Docker image for Management Services is set to 4.1.0. In this effort to upgrade Sitecore CLI, the Docker Image must be 5.1.25. To find the right image, Sitecore publishes a list of images here:
The image for this is listed here in the Docker images from Sitecore:
5.1.25-1809 | 10.0.17763.3406 | 1809 | amd64 | windows | sha256:e365ce2096dadf26386a5f170d7d0b8905a5fb51124f369c43f67c81211cd854 | 10/12/2022 16:30:25 | 10/12/2022 16:30:25|
Now we need to go back to our .env
and update the Management Services reference:
MANAGEMENT_SERVICES_IMAGE=scr.sitecore.com/sxp/modules/sitecore-management-services-xm1-assets:5.1.25-1809
Dockerfile
Applying the changes may not be as easy as bringing the containers down and back up. First, the Management Services Image is set within the environment file. In this case, it has no impact when the container is brought up. Second, the CM container is based on an image built with the previous Management Services module, so the image must be rebuilt for the CM container to have the appropriate updated version.
Let's work out a couple of Docker commands to address this.
- Pull Management Services image.
docker pull "scr.sitecore.com/sxp/modules/sitecore-management-services-xm1-assets:5.1.25-1809"
We won't have the image for 5.1.25, so let's ensure we have it.
2. Find our container for CM.
$container = "$(docker container ls -q --filter name=[cm_container_name])"
cm_container_name
is a placeholder to replace the name of the container instance running Sitecore (Content Management or Standalone).
We will use $container
in subsequent commands to address the running container. If the container is stopped and removed, this step and the next step will be unnecessary.
3. Stop and remove the container so the image can be removed.
docker container stop $container
docker container rm -f $container
4. Remove the CM image
docker rmi [cm_image_name]
cm_image_name
is a placeholder to replace the image built for your Sitecore container.
5. Build a new CM image
docker-compose build --no-cache cm
Note --no-cache
is important as the build may take the cached image. Additionally, the name cm
should match the name used in the Docker Compose file for Sitecore.
6. Start the container for CM
docker-compose up -d
This will start whatever is not running. To target the CM container, the service can be specified.
docker-compose up -d cm
Changes for the Team
Applying the changes across the team may not be as easy as pulling the latest from source control. Also, as we found out, they cannot just bring the containers down and back up. First, the Management Services Image is set within the .env
file, and this file is not tracked by source control. Second, they need an easy way to rebuild and start their new CM container.
A PowerShell script can be checked in for every developer to run after they pull the latest.
We need the PowerShell script to handle everything:
- Set
MANAGEMENT_SERVICES_IMAGE
to the newer version of the image and pull the image. - Stop and review the CM container.
- Remove the image that was built for the CM container.
- Build a new image for CM.
- Start up the CM container.
- Restore
dotnet
tool for Sitecore CLI 5.1.25.
We can combine everything we did to get our Docker container setup with additional helpful steps. To update the environment file, the script must utilize Sitecore Docker Tools. Version 10.2.7 was used for this script.
# Check for Sitecore Gallery
Import-Module PowerShellGet
$SitecoreGallery = Get-PSRepository | Where-Object { $_.SourceLocation -eq "https://sitecore.myget.org/F/sc-powershell/api/v2" }
if (-not $SitecoreGallery) {
Write-Host "Adding Sitecore PowerShell Gallery..." -ForegroundColor Green
Register-PSRepository -Name SitecoreGallery -SourceLocation https://sitecore.myget.org/F/sc-powershell/api/v2 -InstallationPolicy Trusted
$SitecoreGallery = Get-PSRepository -Name SitecoreGallery
}
# Install and Import SitecoreDockerTools
$dockerToolsVersion = "10.2.7"
Remove-Module SitecoreDockerTools -ErrorAction SilentlyContinue
if (-not (Get-InstalledModule -Name SitecoreDockerTools -RequiredVersion $dockerToolsVersion -ErrorAction SilentlyContinue)) {
Write-Host "Installing SitecoreDockerTools..." -ForegroundColor Green
Install-Module SitecoreDockerTools -RequiredVersion $dockerToolsVersion -Scope CurrentUser -Repository $SitecoreGallery.Name
}
Write-Host "Importing SitecoreDockerTools..." -ForegroundColor Green
Import-Module SitecoreDockerTools -RequiredVersion $dockerToolsVersion
Write-SitecoreDockerWelcome
Then we can add the step to set the MANAGEMENT_SERVICES_IMAGE
with Set-EnvFileVariable
and pull the image.
$managementServicesImage = "scr.sitecore.com/sxp/modules/sitecore-management-services-xm1-assets:5.1.25-1809"
Set-EnvFileVariable "MANAGEMENT_SERVICES_IMAGE" -Value $managementServicesImage
Write-Host "Pull new Sitecore Management Services image..." -ForegroundColor Green
docker pull $managementServicesImage
Next, the steps to handle the container and the image.
$container = "$(docker container ls -q --filter name=[cm_container_name])"
Write-Host "Stopping [cm_container_name]..." -ForegroundColor Green
docker container stop $container
Write-Host "Remove container [cm_container_name]..." -ForegroundColor Green
docker container rm -f $container
Write-Host "Remove image [cm_image_name]..." -ForegroundColor Green
docker rmi [cm_image_name]
Write-Host "Build Docker image for cm..." -ForegroundColor Green
docker-compose build --no-cache cm
Write-Host "Start container [cm_container_name]..." -ForegroundColor Green
docker-compose up -d
Finally, let's restore the dotnet
tool for updating Sitecore CLI.
Write-Host "Dotnet Tool Restore for Sitecore CLI 5.1.25..." -ForegroundColor Green
dotnet tool restore
Write-Host "Done!" -ForegroundColor Green
The entire script can be found here: https://gist.github.com/edames/6ecf42761e7cf31152143e89d493fa81
The blog post is part of a series of blog posts on how to upgrade Sitecore CLI with Docker and manage the tooling with deployment tooling. Going back to our process diagram:

This series will touch on these areas and how upgrading Sitecore CLI requires more to think about.
If automated checks are part of the process to validate a healthy branch, these checks will need to be validated that the upgrade for Sitecore CLI has not impacted that automation. The next blog post will touch on some of this.