Workflow for creating custom Commerce container images


How to build your own Commerce container images using the resources provided in the Sitecore Commerce Container SDK.

After you have finished developing a feature or a complete solution that you can successfully run in Visual Studio, you can create container images of your new commerce solution for deployment.


This workflow assumes that you have already downloaded and extracted the Sitecore.Commerce.Container.SDK.ZIP package on your developer workstation.

Make sure to familiarize yourself with the contents of the Sitecore Commerce Container SDK and with the script files it provides.

Before you proceed:

  • Ensure to use Docker Compose version 1.27.4 (or earlier) to build your custom XC containers. To verify the version of Docker Compose, you can run the docker-compose --version command.

  • Keep all topology folders for Docker containers in the Sitecore Commerce Containers SDK folder. The topology folders share resources that are required to successfully build your custom containers.

To create your own Sitecore XC container images:

The WDPMapping.json file contains mapping information that is used to place the content of the Sitecore Experience Commerce (XC) release package artifacts in the correct location for the docker-compose build to process.


The first time you create XC containers with your own Commerce Engine solution, you must remove the reference to the default sample Commerce Engine WDP (Sitecore.Commerce.Engine.OnPrem.Solr), that is part of the Sitecore XC Release Package.

You should remove reference to any WDPs from the packages that corresponds to areas you have customized to avoid overwriting your customization with the default release packages. For example, if you have customized the Commerce Business Tools, you must remove the Sitecore.BizFx.OnPrem block from the WDPMapping.json file.

To update the WDPMappings.json

  1. Open the Sitecore.Commerce.Container.SDK.*.*.***/scripts/WDPMapping.json.

  2. Remove the sample Commerce Engine WDP:

        "WDPs": [
        "DestinationFolder": "xc-common/engine/wdp",
        "ToCopyFolder": "Content/Website"
  3. If you have customized the XC Business Tools, you should also remove the following section containing the mapping to the Sitecore.BizFx.OnPrem package:

        "WDPs": [
        "DestinationFolder": "xc-common/bizfx/wdp",
         "ToCopyFolder": "Content/Website"

By default, the build process for Commerce containers uses the image with the latest tag. If you want your container to include a specific image, you must update the configuration with the tags corresponding to the version of the images you want to use.

The configuration file you modify depends on the version of Windows OS tags. Modify the JSON file that corresponds to the version of Windows OS hosting your containers, that is config2019.json or configltsc2019.json

To add your custom image tags to the configuration:

  1. Open the appropriate JSON file based on the OS running on the host, that is config2019.json or configltsc2019.json.

  2. Replace the value of the "customercommercetag" with the appropriate tag value.

To containerize your Commerce Engine customization, you must add your custom code or binaries to the appropriate Sitecore.Commerce.Container.SDK folder. The location in the SDK folder structure where you add your custom artifact depends on the area of the solution your customization affects.

  • Add Commerce Engine customization artifacts to the following folder: xc-common/engine/wdp/


    You must create the wdp folder.

  • Add your Business Tools customization to the folder: xc-common/engine/bizfx/wdp


    You must create the WDP folder.

  • You add custom artifacts affecting the Content Delivery (CD) or Content Management (CM) role to the following location:

    • Add CM customization to this folder: xc0/cm/content/website

    • Add CD customization to this folder: xc1/cd/content/website


    When you add custom files to the xc0/*/content/website folder, you must replicate the same folder structure as the root folder of the CD or CM instance. The "xc0/*/content/website" folder is the equivalent to the inetpub/wwwroot/<CD or CM instance> folder.

    For example, if you have a CD customization that includes new binaries files, you create a bin folder containing your new binaries at the root of the content/website/ folder (for example xc0/cd/content/website/bin), to match the structure of the CD root folder ( inetpub/wwwroot/SXAstorefront/bin).

You use the UpdateEnvTag.ps1 tag to update the .env file with new image tag values from the config2019.json or configltsc2019.json files.

To update the environment variables with new tag values:

  • Open a PowerShell window, and run the following command:

    UpdateEnvTag.ps1 -jsonFile 'C:\sitecore-commerce\scripts\configltsc2019.json' `
                     -envRootPath 'C:\sitecore-commerce' 

You use the PrepContainerbuild.ps1 script to take artifacts from the location of the Sitecore Experience Commerce release packages on your machine, and expand them into the Sitecore.Commerce.Container.SDK directory structure. The PrepContainerbuild.ps1 copies the packages in a location as predefined in the WDPMapping.json.

To get the content of images:

  1. Download the following Sitecore Experience Commerce release packages from the Sitecore Downloads site:

    • Packages for On Premise WDP ****.**.**-*.*.***

    • Packages for Azure App Service ****.**.**-*.*.***.


    The PrepContainerbuild.ps1 script that is used to prepare the container build includes references to WDPs within these release packages.

  2. To get the container images, open a PowerShell window, and run the following command:

    PrepContainerbuild.ps1 -jsonFile 'C:\sitecore-commerce\scripts' -releaseZipPath 'C:\downloads'

To build your container images:

  1. Open a PowerShell window, and run the following command:

    ContainerBuild.ps1 -envRootPath 'C:\sitecore-commerce'
  2. Confirm that the images were created by listing all Docker images:

    docker images