Building Docker images for older versions of Sitecore

There’s been a lot of movement towards “Docker for Sitecore” over the last year – to the extent that even I have finally jumped onto the bandwagon. And with any new tech, there are some rough edges to contend with. Right now (for me at least) one of those is being able to get the right Docker images built for the bit of work you need to do. In the future (crosses fingers) we’ll see Sitecore offering a repo for these images – but for now it’s up to us to build our own. So if you need something that’s not v9.3, here’s what I did to get there:

Updated: After I asked about these challenges on Sitecore Slack, Michael West took up the challenge to try and make the build script better. He’s done some great work to add filter parameters so that you can easily specify things like the Sitecore and Windows version(s), the presence of SPE, or whether you need XM or XP images.

So grab the latest version of the repository and give give his improvements go…


When you go to Sitecore’s github repo for Docker container builds and run their “build.ps1” script right now, what you end up with is a shiny set of v9.3 containers. Great for experimenting – but I find myself with a load of development work in earlier versions still. Hence I needed to spin up containers for v9.2 – and it wasn’t initially obvious to me how to achieve that…

When you run the build.ps1 script, some of the early output is a list of all the images it knows how to build, and whether it’s going to or not:

Reading through that (or looking at the folders under \windows\ in the repo will show that it clearly knows how to generate older versions – but it chooses not to. The “Include” column in the output above is false for everything that’s not v9.3.

So where does that choice come from? Well if you delve through the script in the repo’s \modules\SitecoreImageBuilder\ folder you’ll find that there are two commandlets there for generating images. Invoke-PackageRestore does the downloading of Sitecore files for you, and Invoke-Build uses those downloads to generate Docker images. Both of these commandlets have a “Tags” parameter:

[Parameter(Mandatory = $false)]
[array]$Tags = (Get-LatestSupportedVersionTags)

And as you can see, it defaults to “get the latest version”. So if you want to build something else, you need to specify the right value for these parameters.

So what’s right then? Well, if you look back at the list of tags above, you’ll see they generally follow a pattern: “Sitecore”, followed by, the platform config (XM/XP), the role (SQL, xConnect), whether things like SXA or PSE are included, the release version and finally what Windows image to build on top of. So the right data to pass is a string which can filter these values down to whatever you want.

I was after an XP release of v9.2, so initially the pattern I tried was “sitecore-xp-*:9.2.0*“. The wildcards there allow it to match all the tags for that pattern. And that happily changes the list of tags to build to include all the v9.2 stuff:

But, it turns out that the upstream respositories of Windows images do not necessarily include everything you think they might. Trying to run that build failed, with an error about being unable to pull down the base image for a specific Windows Server release:

For google’s sake, the error is:

### External image 'mcr.microsoft.com/windows/nanoserver:1903' is latest.
1909: Pulling from windows/servercore
no matching manifest for windows/amd64 10.0.18362 in the manifest list entries
Failed.
At C:\docker\docker-images\modules\SitecoreImageBuilder\SitecoreImageBuilder.psm1:214 char:78
+ ... CODE -ne 0 | Where-Object { $_ } | ForEach-Object { throw "Failed." }
+                                                         ~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (Failed.:String) [], RuntimeException
    + FullyQualifiedErrorId : Failed.

So to get my build to work correctly, I had to adjust my tag filter to use only the available base images. The 1903 Windows release is available for everything, so this tag allowed the build to complete: “sitecore-xp-*:9.2.0*1903

Now, I’ve skipped over a key point here: the build.ps1 script doesn’t actually allow you to pass in the Tags parameter that the internal commandlets need, so how do you actually make it work for this? Well you have two options:

The first is just changing the build script, to include your required tags in the calls to the download and build commandlets. Editing the end of the file to look like:

$ErrorActionPreference = "STOP"
$ProgressPreference = "SilentlyContinue"

# load module
Import-Module (Join-Path $PSScriptRoot "\modules\SitecoreImageBuilder") -Force

# restore any missing packages
SitecoreImageBuilder\Invoke-PackageRestore `
    -Path (Join-Path $PSScriptRoot "\windows") `
    -Destination $InstallSourcePath `
    -SitecoreUsername $SitecoreUsername `
    -SitecorePassword $SitecorePassword `
    -WhatIf:$WhatIfPreference `
    -Tags "sitecore-xp-*:9.2.0*1903"

# start the build
SitecoreImageBuilder\Invoke-Build `
    -Path (Join-Path $PSScriptRoot "\windows") `
    -InstallSourcePath $InstallSourcePath `
    -Registry $Registry `
    -WhatIf:$WhatIfPreference `
    -Tags "sitecore-xp-*:9.2.0*1903"

You probably want to save that with a new (and descriptive) name…

Or alternatively you can change build.ps1 to accept your choice of tags as an optional parameter. Firstly, add it to the parameter list at the start of the file:

    [Parameter(Mandatory = $false)]
    [string]$RegistryPassword = ""
    ,
    [Parameter(Mandatory = $false)]
    [string]$Tags = ""

And then change the commandlet calls to pass it through:

# restore any missing packages
SitecoreImageBuilder\Invoke-PackageRestore `
    -Path (Join-Path $PSScriptRoot "\windows") `
    -Destination $InstallSourcePath `
    -SitecoreUsername $SitecoreUsername `
    -SitecorePassword $SitecorePassword `
    -WhatIf:$WhatIfPreference `
    -Tags $Tags

# start the build
SitecoreImageBuilder\Invoke-Build `
    -Path (Join-Path $PSScriptRoot "\windows") `
    -InstallSourcePath $InstallSourcePath `
    -Registry $Registry `
    -WhatIf:$WhatIfPreference `
    -Tags $Tags

And you can get on and build just the images you need…

2 thoughts on “Building Docker images for older versions of Sitecore

    • Ah yes – sorry – this doesn’t apply to stuff pre v9. If you want to build for v7.5 to v8.2 you can look in the “legacy\tests” folder in the repo. There are folders in there with Dockerfiles for those releases. They don’t appear to be integrated into the overall “build everything” script though.

      (Not run these myself yet, mind)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.