Workflow for creating custom Commerce container images

Version: 10.3

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.

To create your own Sitecore XC container images:

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, and so on.

To add your custom image tags to the configuration:

  1. Open the appropriate JSON file based on the OS running on the host.

  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.

To add your customization to the Sitecore Commerce Container SDK:

  1. Add your Commerce Engine customization artifacts to the following folder:

    RequestResponse
    xc-common/engine/wdp/
    Note

    You must create the WDP folder.

  2. Add your Business Tools customization to the folder following folder:

    RequestResponse
    xc-common/engine/bizfx/wdp
    Note

    You must create the WDP folder.

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

    • Add CD customization to this folder: xc1/cd

Update the environment variables with image tag values

You use the UpdateEnvTag.ps1 script to update the .env file with new image tag values contained in the configuration file corresponding to the appropriate Windows OS version, for example from the config2009.json or configltsc2019.json files, and so on.

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

Sitecore Experience Commerce provides the following XC asset images that you layer on top of the base Sitecore XP images:

  • sitecore-xc0-assets – which overlay on top of sitecore-xp0* images

  • sitecore-xc1-assets –which overlay on top of sitecore-xp1* images

  • sitecore-xc1-storefront-assets – which overlay on top of xc1-assets

For an example of how to use the XC asset images, you can review the contents of the xc0, xc1 and xc1-cxa folders in the Sitecore Experience.Commerce.Container.SDK.

You can use the PrepEngineContainerbuild.ps1 script to take artifacts from the location of the Sitecore Experience Commerce release packages on your machine, and expand them into the appropriate location within the directory structure of the Sitecore.Commerce.Container.SDK. The PrepEngineContainerbuild.ps1 copies the packages in a location predefined within the script file.

Note

The purpose of the PrepEngineContainerbuild.ps1 script is to place the artifacts for the Sitecore Commerce Engine and the Business Tools (BizFx) only.

The following shows how to use the Commerce Engine and BizFx content provided out of the box to create a custom Commerce Engine or BizFx image.

To get the content for container images:

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

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

    Note

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

  2. Extract the contents of the release package to a separate folder, for example, c:\downloads\wdps.

  3. To place the contents packages in the expected location for building the container images, open a PowerShell window, and run the following command:

    RequestResponse
    PrepEngineContainerbuild.ps1 -wdpPath 'C:\downloads\wdps

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,