Applying configuration transforms

Navigate to the custom-images folder, and look at the Dockerfile that is there.

You' can see that the transform files (.xdt extension) are collected within the builder stage and dropped at C:\out\transforms. The use of robocopy (along with the /s flag) is important here because it preserves the folder structure:

RUN Invoke-Expression 'robocopy C:\build\src C:\out\transforms /s /ndl /njh /njs *.xdt'

Note this is done before the msbuild so you do not have to pick up extra .xdt files that have not been excluded from build output. Then these files are copied in from the builder stage to the final image with this structure: \artifacts\transforms:

COPY --from=builder C:\out\transforms .\transforms\

To apply transforms to runtime images:

The Invoke-XdtTransform.ps1 script accepts two folders for the -Path and -XdtPath parameters. When using folders:

In this case, -Path is the current WORKDIR of C:\inetpub\wwwroot, and -XdtPath is the root of our single Visual Studio Website project.

The Helix solution example

The Docker Examples solution is a simple example with a single Website project. In a real-world solution that follow the Sitecore Helix practices, the transform commands would need to be adjusted to reflect the nested folder structure and layer priority (such as Project, Feature, Foundation):

RUN Get-ChildItem C:\transforms\solution\Foundation\*\website | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath $_.FullName }; `
    Get-ChildItem C:\transforms\solution\Feature\*\website | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath $_.FullName }; `
    Get-ChildItem C:\transforms\solution\Project\*\website | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath $_.FullName };

You can keep the transform files with all other files in the main build output. The disadvantage to this approach is that it does not support multiple transforms for the same config file, but it can be your only option if you do not have a solution build Dockerfile and image and instead rely on a more traditional build.

The following is an example:

RUN $xdts = [System.Collections.ArrayList]@(); `
    $xdts.AddRange(@(Get-ChildItem -Path .\*.xdt)); `
    $xdts.AddRange(@(Get-ChildItem -Path .\App_Config\*.xdt -Recurse)); `
    $xdts | ForEach-Object { & C:\tools\scripts\Invoke-XdtTransform.ps1 -Path $_.FullName.Replace('.xdt', '') -XdtPath $_.FullName }; `
    $xdts | ForEach-Object { Remove-Item -Path $_.FullName };

The Invoke-XdtTransform.ps1 script also accepts matching configuration and transform files as parameters.

This example looks for .xdt files in the web root and App_Config folder, passes them through the Invoke-XdtTransform.ps1 script, and then deletes the .xdt files.

Navigate to the docker\build folder for the cm service. Note there is an extra transforms folder for this role:

build
    cm
        transforms
            Web.config.xdt
        Dockerfile

There is a single Web.config.xdt transform, but this transform can contain any other transforms necessary for the cm role. As is the case with solution transforms, you structure the transform files to match the folder structure of your target.

You then apply these transforms in the Sitecore runtime Dockerfile for the role.

You can see in the Sitecore runtime Dockerfile for the cm service that the transforms folder contents are copied in from the Docker build context, landing at \transforms\role\:

COPY .\transforms\ \transforms\role\

The transforms are then applied after solution transforms, using the same Invoke-XdtTransform.ps1 script:

RUN C:\tools\scripts\Invoke-XdtTransform.ps1 -Path .\ -XdtPath C:\transforms\role