Workflow for creating custom Commerce container images

Current version: 10.1

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.

Note

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:

Update the WDP mapping file

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.

Note

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 correspond to areas of the solution 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:

    RequestResponse
    {
        "WDPs": [
            "Sitecore.Commerce.Engine.OnPrem.Solr"
        ],
        "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:

    RequestResponse
    {
        "WDPs": [
             "Sitecore.BizFx.OnPrem"
        ],
        "DestinationFolder": "xc-common/bizfx/wdp",
         "ToCopyFolder": "Content/Website"
    
    }

Add your custom image tags to the configuration

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, for example, config2009.json, config.2004, config20H2.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, for example config2009.json, config2004.json, config20H2.json, or configltsc2019.json.

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

Add your customization to the Sitecore Commerce Container SDK

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/

    Note

    You must create the wdp folder.

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

    Note

    You must create the WDP folder.

  • To include custom artifacts affecting the Content Delivery (CD) or Content Management (CM) role, you must add them into the appropriate WDP folder. The path to the CM and CD folder is, respectively:

    • WDP folder for CM customization: <sdk_directory>xc1-cxa/cm/wdp

    • WDP folder for CD customization: <sdk_directory>xc1-cxa/cd/wdp

    Note

    When you add custom files to the WDP folder, you must replicate the same folder structure as the root folder of the CD or CM instance. The <sdk_directory>xc1-cxa/<CD or CM>/wdp 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 WDP folder, for example sdk_directory>xc1-cxa/cm/wdp/bin), to match the structure of the CD root folder ( inetpub/wwwroot/SXAstorefront/bin).

Update the environment variables with image tag values

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

To update the environment variables with new tag values:

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

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

Get content for container images

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 package from the Sitecore Downloads site:

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

    Note

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

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

    RequestResponse
    PrepContainerbuild.ps1 -jsonFile 'C:\src\Commerce.Containers\WDPMapping.json' -releaseZipPath 'C:\src\Commerce.Containers\downloads'

Build your container images

To build your container images:

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

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

    RequestResponse
    docker images

Do you have some feedback for us?

If you have suggestions for improving this article,