Upgrade Sitecore CLI and Docker

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:

https://raw.githubusercontent.com/Sitecore/docker-images/master/tags/sitecore-tags.mdhttps://raw.githubusercontent.com/Sitecore/docker-images/master/tags/sitecore-tags.md

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.

  1. 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:

  1. Set MANAGEMENT_SERVICES_IMAGE to the newer version of the image and pull the image.
  2. Stop and review the CM container.
  3. Remove the image that was built for the CM container.
  4. Build a new image for CM.
  5. Start up the CM container.
  6. 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.