Sitecore 10.1 introduced a great new feature for local development with containers: development-only configuration. This feature allows you to apply config transformations to your solution for local development only, without affecting your sites in production. Some examples of this are setting customErrors="Off" or compilation debug="true" in the Web.config.

The Sitecore 10.1 Docker Tools assets image that contains the development-only configuration feature is backwards compatible with Sitecore 10.0, so backporting this functionality to Sitecore 10.0 is pretty easy. In this post I'll show you how.

TL;DR

All of the code for this tutorial is on GitHub:

Caveat

If you're on Sitecore 10.0 Initial Release or Update-1, you should update your solution to Sitecore 10.0 Update-2 immediately. Sitecore announced a critical security vulnerability in June that is fixed in Sitecore 10.0 Update-2.

Sitecore 10.0 Update-1 and Update-2

Update your .env to point to the 10.1 version of the Docker Tools image and set the configuration transforms you want applied locally (see the full list here):

TOOLS_VERSION=10.1-1809

SITECORE_DEVELOPMENT_PATCHES=CustomErrorsOff,DebugOn,OptimizeCompilationsOn

Update your CM/CD services to use the new SITECORE_DEVELOPMENT_PATCHES environment variable:

services:
  cd:
    environment:
      SITECORE_DEVELOPMENT_PATCHES: ${SITECORE_DEVELOPMENT_PATCHES}
  cm:
    environment:
      SITECORE_DEVELOPMENT_PATCHES: ${SITECORE_DEVELOPMENT_PATCHES}

That's it. Now all of the patches you specify in the SITECORE_DEVELOPMENT_PATCHES environment variable will be applied to your CM and CD containers the next time they run.

Sitecore 10.0 Initial Release

Again, I stress that if you are on 10.0 Initial Release, you should stop now and upgrade to Sitecore 10.0 Update-2 to address the critical security vulnerability announced in June. Docker makes this upgrade easy, so don't delay, act now.

Backporting the 10.1 Docker Tools to work with 10.0 Initial Release is a little more work than for 10.0 Update-1 and Update-2, but still pretty easy.

Update your .env to point to the 10.1 version of the Docker Tools image and set the configuration transforms you want applied locally (see the full list here):

TOOLS_VERSION=10.1-1809

SITECORE_DEVELOPMENT_PATCHES=CustomErrorsOff,DebugOn,OptimizeCompilationsOn

For Sitecore 10.0 Initial Release, you have to create a custom Docker Tools image to fix an incompatibility between the Sitecore 10.1 entrypoint and the Sitecore 10.0 Initial Release images. Create a new Dockerfile as follows in your build folder (e.g., docker/build/tools):

# escape=`

ARG BASE_IMAGE
ARG BUILD_IMAGE

FROM ${BASE_IMAGE} as tools
FROM ${BUILD_IMAGE} as builder
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

COPY --from=tools C:\tools C:\tools

# The Development entrypoint script in the 10.1 tools image is not compatible
# with Sitecore 10.0 Initial Release. This script fixes that incompatibility.
# This should be removed when upgrading to Sitecore 10.0 Update-1 or newer.
COPY FixDevelopmentEntrypoint.ps1 .
RUN C:\FixDevelopmentEntrypoint.ps1 -Path C:\tools\entrypoints\iis\Development.ps1

FROM ${BASE_IMAGE}

COPY --from=builder C:\tools C:\tools

This copies all of the assets from the 10.1 Docker Tools image and then runs a script to modify the 10.1 entrypoint to work with Sitecore 10.0 Initial Release.

Create a PowerShell script called FixDevelopmentEntrypoint.ps1 alongside the Dockerfile (e.g., in docker/build/tools):

[CmdletBinding()]
param (
    [Parameter(Mandatory)]
    [ValidateScript({ Test-Path $_ -PathType Leaf })]
    [string]$Path
)

(Get-Content $Path).Replace( `
    '& "C:\LogMonitor\LogMonitor.exe" "powershell" "C:\Run-W3SVCService.ps1"', `
    '& "C:\LogMonitor\LogMonitor.exe" "C:\ServiceMonitor.exe" "w3svc"') | `
    Set-Content $Path

The 10.0 Initial Release images are not compatible with the Run-W3SVCService.ps1 entrypoint; this modifies the script to match the entrypoint that is in the 10.0 Initial Release Docker Tools.

⚠️Note⚠️: when you upgrade to Sitecore 10.0 Update-1 or later, remove this script and lines 12-16 in the custom Docker Tools Dockerfile above.

Update your Docker Compose file (or override file) to build your custom tools image (updating context and other parameters as necessary to match your solution):

services:
  tools:
    image: ${REGISTRY}${COMPOSE_PROJECT_NAME}-sitecore-docker-tools-assets:${VERSION:-latest}
    build:
      context: ./docker/build/tools
      args:
        BASE_IMAGE: ${SITECORE_TOOLS_REGISTRY}sitecore-docker-tools-assets:${TOOLS_VERSION}
        BUILD_IMAGE: ${SOLUTION_BUILD_IMAGE}
    scale: 0

And update your CM/CD services to use the new tools image and the SITECORE_DEVELOPMENT_PATCHES environment variable:

services:
  cd:
    build:
      args:
        TOOLING_IMAGE: ${REGISTRY}${COMPOSE_PROJECT_NAME}-sitecore-docker-tools-assets:${VERSION:-latest}
    depends_on:
      - tools
    environment:
      SITECORE_DEVELOPMENT_PATCHES: ${SITECORE_DEVELOPMENT_PATCHES}
  cm:
    build:
      args:
        TOOLING_IMAGE: ${REGISTRY}${COMPOSE_PROJECT_NAME}-sitecore-docker-tools-assets:${VERSION:-latest}
    depends_on:
      - tools
    environment:
      SITECORE_DEVELOPMENT_PATCHES: ${SITECORE_DEVELOPMENT_PATCHES}

Now all of the patches you specify in the SITECORE_DEVELOPMENT_PATCHES environment variable will be applied to your CM and CD containers the next time they run.

Thanks to my friends Zach Gay and Jean-François L'Heureux for reviewing this post.