Sitecore Docker images repository

The Sitecore Docker images repository is an open source GitHub repository which you can access here today. It has been created with a large amount of contributions from the community and is constantly evolving on the back of this. Once you clone the repository you not only get examples of how to build fully functional Sitecore Docker images, but also samples showing how you can compose them together into a complete system.

** Update November 2020 ** With our recent Docker updates you no longer need to build your own Sitecore container images. You now have a couple of options for how to get pre-built Sitecore Docker images, depending on which version you are running.

If you're running on Sitecore 10+ you can now follow the documentation here to get started using our fully supported official Docker images.

If you’re using the community images, you can now find the v10+ community images pre-built for you in our public ACR, details here. Note that this doesn’t change the support details for these images as listed here.

Watch the video accompanying this article below, which includes demos of these concepts. Or watch it on Discover Sitecore on YouTube.

The images are built by a PowerShell script that you will find in the root of the repository called Build.ps1. You can control what is built through a series of parameters that you pass in when executing it:

For example, to build all of the latest version images for Sitecore Experience Manager (XM), Sitecore Experience Platform (XP) and Sitecore Experience Commerce (XC) including all of the different variants you would run the following command:

.\Build.ps1 -SitecoreUsername <YOUR_USERNAME> -SitecorePassword <YOUR_PASSWORD> -Topology "xm", "xp", "xc" -IncludeSpe -IncludeSxa -IncludeJss

The build script will then use your username and password to download all of the required packages from dev.sitecore.net. The script will then build all of the images you've requested.

Note: Running a complete build of images fresh usually takes around two hours to complete depending on the system resources you have available.

Changing the parameters above alters what images are built by the script. The images themselves are built to leverage the key Docker concept of Layers. Layers allow you to take an existing Docker image and build on top of it to extend the functionality provided. This concept fits well with the various Sitecore products available. Consider comparing a standard Content Management (CM) instance with a CM that also has SPE installed. The SPE image takes all of the CM functionality and builds on top of it.

If you look at the image here you can see how these layers frequently come into play and how they build on top of the functionality introduced in the layer below, e.g.

XC SXA Storefront Standalone -> XC SXA Standalone -> XC SPE Standalone -> XC Standalone -> XP Standalone -> aspnet:4.8:windowservercore-ltsc2019

Note: The images are being inherited by various other images, however they are shared and actually only exist on disk once.

Building all of these images will take up some room on your hard drive to store them all. If you look at the image below you can see a list of images that have been built with the sizes of those images listed. However, the sizes listed there are not a true reflection of the actual size on disk.

If you look at the highlighted rows above, they show the XM CD and CM images and the aspnet:4.8:windowservercore-ltsc2019 image they both inherit from. At first glance it might look like they would take up the following amount of space on disk:

However, that's not the case. As mentioned above, the images are shared and only exist once on disk. So we need to subtract the aspnet size from the CD and CM sizes to get their true size:

So you can see that while some disk space is required for these images, the amount output by Docker is not the true amount of disk space used.

Note: The build process creates a series of what are called “dangling” or “intermediary” images as part of the build process. These will take up disk space but are not needed after the build is completed. To remove them you can use a system prune command by typing:

docker system prune

Once you've built the images you require you're going to want to use them to stand up a fully functional Sitecore architecture. The Docker images repository comes with a series of examples of how you can achieve this using Docker Compose. Before we can stand up some containers, though, we first need to store our license information in an Environment variable that the container will then use.

The Sitecore Docker images repository is a guide for how to build shared Sitecore Docker images, so it's not possible to store the License file in there at build time. Doing this would also introduce difficulties when the license expires as this would then require the images to be rebuilt with the new license. A better way to approach this is to pass the license information in at runtime and there is a script in the root of the repository that will store your license information in an Environment variable. You can call it like so:

.\Set-LicenseEnvironmentVariable.ps1 -Path <<PATH-TO-YOUR-LICENSE-FILE>>

Once this is set we can then take a look inside the '/Windows/Tests/9.3.0' folder of the repository to see the example docker compose files. There are a series of samples covering the various topology and variant combinations available. For example, if you wanted to stand up an instance of Sitecore XM with SPE included you could use the following command:

docker-compose -f docker-compose.xm.spe.yml up -d

If you wanted to create an instance of Sitecore Experience Commerce™ (XC) complete with the SXA Storefront, then you would use:

docker-compose -f docker-compose.xc.sxa.storefront.yml up -d

After the containers are created you can then access them using the ports mapped in the docker-compose file you chose to use. Once you've finished with the containers, taking them all down again and tidying up your system is just as simple. To remove the instances we created above, you would use one of the following two commands:

docker-compose -f docker-compose.xm.spe.yml down

docker-compose -f docker-compose.xc.sxa.storefront.yml down

Note: The containers are configured to use Docker Volumes to store some of their data in folders on the host machine, e.g. the SQL Databases and Solr indexes. If you want to switch between different instances of Sitecore, you will need to remove these temporary files first by using the Clean-Data.ps1 script located in the same 9.3.0 folder.

As the build process can take a couple of hours to complete, it's not practical to have each developer build their own images. Instead, if you're working in a team you will want to leverage a Docker Registry to store your built images. Each developer can then pull images from the registry, which is much faster than building the images individually. Some of the more commonly used Docker Registries are:

• Docker Hub
• Azure Container Registry
• Amazon Elastic Container Registry

Once you have configured one of these providers, you can then use the “Registry” parameter for the Build.ps1 script. Running your build with the “Registry” parameter specified will then also push the images into this registry as they are completed.

Note: You must ensure that you must push your images to a Private Registry and not a Public Registry. Sitecore software is not publicly available, so any images you created must be hosted behind an authentication gateway.

• If you don't want to wait for the packages to be downloaded from dev.sitecore.net, or you already have them downloaded, you can copy them into the '/.packages' folder at the root of the repository and that step will be skipped.
• As we're running Windows containers, you will need to ensure that you have Docker configured to run in 'Windows Container' mode.
• If you want to switch between different Sitecore architectures, for example changing from an XM instance to an XP instance, you will need to ensure you run the CleanData.ps1 script first to tear down any temporary assets from the prior system.
• You should check your system's power management settings if you intend to walk away from your machine while the build executes, as you don't want your machine to turn off halfway through due to a lack of user activity.
• If disk space is becoming an issue, you can use a 'docker system prune' command to remove any dangling intermediary images.

Thanks for reading and make sure to follow #LearnSitecore for future content!

Rob Earlam, Technical Evangelist, Sitecore
https://robearlam.com/