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:
- Sitecore 10.0 Initial Release: https://github.com/coreyasmith/sitecore-docker-dev-only-configs/tree/v10.0.0
- Sitecore 10.0 Update-1 and Update-2: https://github.com/coreyasmith/sitecore-docker-dev-only-configs/tree/v10.0.2
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.