Table of contents
Table of contents
- How do you build the images?
- What images are built?
- Image sizes on disk
- How to use the images?
- Pushing to a Docker registry
- Tips and tricks
Leverage a Docker Registry so each developer can pull images from the registry which is faster than building images individually.
Watch the video accompanying this article below, which includes demos of these concepts. Or watch it on Master Sitecore on YouTube.
How do you build the images?
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:
|SitecoreUsername||Yes||None||Your username for https://dev.sitecore.net/|
|SitecorePassword||Yes||None||Your password for https://dev.sitecore.net/|
|SitecoreVersion||No||9.3||The versions of Sitecore you want to build images for. The repository contains instructions on how to build images for every version of Sitecore from 9.0.2 to the current version.|
|Topology||No||"xm", "xp"||The Sitecore products that you want to build images for, possible values are "xm", "xp" or "xc". Multiple can be specified at the same time.|
|WindowsVersion||No||ltsc2019||The base windows version you want to build images for, possible values are "1909", "1903" & "ltsc2019"|
|IncludeSpe||No||False||Switch parameter to include images with Sitecore PowerShell Extensions (SPE) installed|
|IncludeSxa||No||False||Switch parameter to include images with Sitecore Experience Accelerator (SXA) installed|
|SkipExistingImage||No||False||Switch parameter to skip attempting to rebuild any existing images|
|IncludeExperimental||No||False||Switch parameter to include images that are marked as experimental|
|Registry||No||""||URL for the Registry to push the built images out to|
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.
What images are built?
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.
Image sizes on disk
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
How to use the images?
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.
Pushing to a Docker registry
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:
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.
Tips and tricks
- 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