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 dual tagging system consisting of a long tag and a short 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.

Long 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

Short tag:

<Sitecore version>-<OS name>

The following is an example tag:

10.0.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.

Long 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

Short tag:

<module version>-<OS name>

The following is an example tag:

14.0.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.

Long tag versus short tag

The long tag locks you to an exact image version.

The short tag allows 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 long or the short tag depends on your build and release process, and how much control over the image version you require. For example, you might use the short tag for development purposes and then transition to the long tag for deployment. If you always want to have the latest image, use the short tag throughout.

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 long 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.