Sitecore image reference

Abstract

Additional information about the Docker images Sitecore makes available.

This topic provides additional information about the images that you find on the Sitecore Container Registry (SCR), scr.sitecore.com, and how you use them in your custom solutions.

You can find a list of available image repositories and tags on the Sitecore Docker Images repository on GitHub.

Sitecore image repositories are organized in the Sitecore Container Registry with namespaces.

Sitecore makes use of several naming conventions to differentiate images:

  • Asset images

    Certain images, such as modules, are intended only as a source during your custom Sitecore image build and you never use them at runtime. These asset images are named accordingly with a -assets suffix. The following are example images:

    • spe-assets

    • sitecore-management-services-xm1-assets

    • sxa-xp1-assets

    • sitecore-docker-tools-assets

  • Topology

    Certain images are specific to a topology. In this case, the topology (-xp0, -xp1, or -xm1) will be included in the name. If an image does not have a topology in the name, then it is topology-independent. The following are example images:

    • sitecore-xp0-cm

    • sitecore-xp1-cortexreporting

    • jss-xm1-assets

All Sitecore images use a tagging system consisting of a full tag, a three-digit tag, and a two-digit tag. In general, the first part of the tag represents the Sitecore or module version, and the rest provides details about the base Microsoft image it is built upon.

Sitecore does not use latest tags because these are too ambiguous and generally not followed by Microsoft or any other OS-based images.

Platform images

Platform images include base images for the Sitecore Experience Platform (scr.sitecore.com/sxp). The Sitecore platform version makes up the first part of the tag.

Full tag:

<Sitecore version>.<Sitecore revision>.<Sitecore build>-<Windows version>.<Windows revision>-<OS name>

The following is an example tag followed by the breakdown:

10.0.0.004346.337-10.0.17763.1339-ltsc2019
<Sitecore version>.<Sitecore revision>.<Sitecore build>-<Windows version>.<Windows revision>-<OS name>
\________________/ \_________________/ \______________/ \_______________/ \________________/ \_______/
         |                  |                 |               |                 |              |
       10.0.0             004346             337          10.0.17763           1339         ltsc2019

Three-digit tag:

<Sitecore version>-<OS name>

The following is an example tag:

10.0.0-ltsc2019

Two-digit tag:

<Sitecore major + minor version>-<OS name>

The following is an example tag:

10.0-ltsc2019

Modules and tools

These include images such as modules for Sitecore Experience Platform (scr.sitecore.com/sxp/modules) and general tools (scr.sitecore.com/tools).

Modules and tools might not have versions that align with the platform. If a module or tool does not align with the platform version, it provides a compatibility matrix in the Sitecore Knowledgebase.

Full tag:

<module version>.<module revision>.<module build>-<Windows version>.<Windows revision>-<OS name>

The following is an example tag followed by the breakdown:

14.0.0.00368.71-10.0.17763.1339-1809
<module version>.<module revision>.<module build>-<Windows version>.<Windows revision>-<OS name>
\______________/ \_______________/ \____________/ \_______________/ \________________/ \_______/
       |                 |               |               |                  |              |
     14.0.0            00368             71          10.0.17763            1339           1809

Three-digit tag:

<module version>-<OS name>

The following is an example tag:

14.0.0-1809

Two-digit tag:

<module major + minor version>-<OS name>

14.0-1809

OS version

When you choose between different OS tags (for example 10.0.0-ltsc2019 versus 10.0.0-1909), follow the same rules used when you choose Microsoft images. Windows requires the host OS version to match the container OS version. If you want to run a container based on a newer Windows build, make sure you have an equivalent host build. Otherwise, you can use Hyper-V isolation to run older containers on new host builds.

For more information about Windows container version compatibility, see the Microsoft documentation.

This is not a problem for asset images because these images are never run. They typically have only one OS tag available.

Full tag versus shorter tags

The full tag locks you to an exact image version.

The three-digit and two-digit tags allow you to be more dynamic, and pull in the latest image version. You lock only the main version (for example, <Sitecore version>) while allowing the remainder (for example, <Sitecore revision>, <Sitecore build>, <Windows revision>) to use the latest.

The choice between using the full tag or one of the shorter tags depends on your build and release process, and how much control over the image version you require. For example, you might use a short tag for development purposes and then transition to the full tag for deployment. If you always want to have the latest image, use a short tag throughout.

Due to the nature of how Sitecore maintains containers and their immutable images, it is best practise to utilize the two-digit tag when creating container images. This ensures the most up-to-date Sitecore container, and that you also automatically get the latest update.

When you use Sitecore image short tags, Docker caches the image digest (an immutable SHA256-based identifier) at the time it is pulled and continues to use it until you either remove the image or explicitly pull the image. You must make sure that you pull the latest image when you need it (for example, for local development and CI environments).

With the recommended setup for Docker Compose, you are able to do most of this with the docker-compose pull command, excluding the overrides:

docker-compose -f docker-compose.yml pull

This command pulls the latest base Sitecore and Traefik images for you. However, any images you use for build purposes (such as asset images for modules and tools) are not pulled. Unfortunately, a docker-compose build --pull is not currently possible due to an issue/limitation in Docker Compose, so you must pull such images individually (with docker pull) or use a full tag for these.

Because it is easy to forget to pull the latest images, you typically automate these commands. You can do this by adding them to your CI build script or a custom up script for local development.