Docker made docker-compose v1 obsolete a while back and the deadline for deprecation and removal from the Docker Desktop application is closing in. Versions released after June 2023 will no longer support docker-compose v1, which has been used in Sitecore and community repositories as local development setup examples for a while. It’s time to get “older” solutions upgraded!

Luckily it’s pretty straight forward. Rob Earlam wrote an excellent post about upgrading the XM-Cloud-Introduction repo on his blog (https://robearlam.com/blog/docker-compose-v2), which will get the job done in most solutions.

However, I’ve hit a few additional gotchas with some solutions that hopefully will avoid some googling or politely asking ChatGPT. Not all are specifically docker-compose v2 related, but snags we hit across teams when carrying out the upgrades.

Traefik volumes

Many Sitecore Docker solutions include the traefik service to be used as a local reverse proxy. It was sometimes defined with volumes mapped like this in example repos:

    volumes:
      - source: \\.\pipe\docker_engine
        target: \\.\pipe\docker_engine

Older versions of Docker Desktop throw an error when bringing this container up. This was seen when using v4.9.0, but not in v4.19.0:

Error response from daemon: Unrecognised volume spec: file ‘\.\pipe\docker_engine’ cannot be mapped. Only directories can be mapped on this platform

Adding in some backslashes to force the engine to interpret this as a directory resolves this issue, and is present in many newer example repositories.

    volumes:
      - source: \\.\pipe\docker_engine\
        target: \\.\pipe\docker_engine\

Env var encoding, literally

Typically the .env file contains a bunch of randomly generated secret, like:

MEDIA_REQUEST_PROTECTION_SHARED_SECRET=some$ecretString

While not directly related to docker-compose v2, it is worth noting that docker desktop (v4.19.0) parses the .env file slightly differently to some earlier versions….not sure where this change happened but there were some “Works on my machine” moments. If a randomly generated secret happens to include a $, and has not been escaped in the .env you will see a warning similar to the following when parsing the .env as part of any docker-compose command.

level=warning msg=”The \”ecretString\” variable is not set. Defaulting to a blank string.”

Easy fix (and good practice) is to ensure that all generated strings that may include special characters are parsed as literals by putting the values in single quotes, preferably as part of init scripts. This should avoid issues when there are differences in versions between the dev team. NB: Double quotes won’t work as they can still be used with parameter expansion!

MEDIA_REQUEST_PROTECTION_SHARED_SECRET='some$ecretString'

Memory on build

Some custom services may require more than 1GB of memory (the default max given to a container in the build stage when using hyperv isolation). For example, if you had hundreds of projects (please don’t) supporting your amazing Helix solution build….it may require more than 1GB memory within the build stages and you would receive Out of Memory exceptions.

In docker-compose v1, the memory parameter can be used to specify the maximum memory used in the build stages.

docker-compose build --memory 2048m

Unfortunately, as it stands right now, this flag is not respected in docker-compose v2, even when using the “classic” build engine. The following warning will be displayed and the default memory (1GB) for the container is used.

WARNING –memory is ignored as not supported in buildkit.

This warning is raised even when NOT using buildkit. However, based on this github issue, it looks like a fix may not be far away. 🤞 So if you’re currently using this flag in your solution keep an eye on when this fix gets rolled into docker desktop.

BuildKit support

BuildKit is the default build engine shipping with docker-compose v2……for Linux images. Unfortunately it doesn’t currently support building windows based images. This is being tracked in this Github issue and will hopefully be available soon. Buildkit has some great new features, but Docker Desktop will continue to ship the “legacy”/”classic” build engine so that windows developers are not impacted….but just don’t get the shiny toys.

Use Docker-compose v2, 🤔

After making all the changes to compose files and scripts, developers will have to start using v2 exclusively in the solution. Help out your fellow devs that miss the memo and make onboarding easier by integrating a version check in scripts to warn/remind them if they still have v1 enabled via docker-compose. NB: docker-compose vs docker compose (ie. the docker CLI)

Often Sitecore solutions have powershell scripts that wrap docker compose commands (you probably just updated them!) e.g. up.ps1. Adding the following snippet may save the team some “derp” time when they go off script and start using docker-compose (with v1 enabled) commands rather than the docker cli.

function Invoke-ComposeVersionCheck {
    Write-Host "CHECKING DOCKER COMPOSE VERSION..."
    $minVersion = 2
    $InstalledComposeVersion = [System.Version]((docker-compose version --short) | Out-String)
    if ($InstalledComposeVersion.Major -lt $minVersion) {
        Write-Host "WARN: Currently using compose v${InstalledComposeVersion}. Ensure you use the docker cli or enabled v${minVersion} for docker-compose" -ForegroundColor DarkYellow
        Write-Host "To enable v2 for docker-compose, use the Docker desktop settings UI or run the following:`n`tdocker-compose enable-v2" -ForegroundColor DarkYellow
    }
    else {      
        Write-Host "docker-compose v${InstalledComposeVersion} in use."  -ForegroundColor Green
    }
}