Jeremy Davis
Sitecore, C# and web development
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 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...
↑ Back to top