1. Getting started with Commerce containers

Sitecore Commerce Container SDK

Version:

The Sitecore Commerce Container SDK provides developers with a starting point for working with a containerized Commerce solution.

The SDK package includes resources such as Docker files, environment variable files, Docker compose YAML files, Kubernetes YAML files, and sample scripts that you can use and modify to:

  • Install Sitecore XC on a developer workstation using containers.

  • Deploy Sitecore Experience Commerce (XC) containers to the Azure Kubernetes Service.

  • Build your own set of containers from your customized Commerce solution.

The Sitecore.Commerce.Container.SDK.*.ZIP package and supporting installation guides are available on the Sitecore Downloads website.

The structure of Sitecore Commerce Container SDK

The Sitecore.Commerce.Container.SDK.*.ZIP package is divided into multiple folders, some containing artifacts required to deploy Sitecore XC in a specific topology, while other folders contain common files, shared across multiple configurations.

At the highest level, the Sitecore.Commerce.Container.*.ZIP package contains the following folders:

Folder name

Description

k8s-commerce-xc1

Contains files required for a Kubernetes XC1 deployment topology.

scripts

Contains a set of supporting scripts and JSON files, provided as examples, that facilitate the creation of the Sitecore Experience Commerce container images using the Docker.

Also contains a README file describing the purpose of each script.

xc0

Contains files used to build and run a Sitecore XC instance in a XC0 topology, for deploying the Commerce Engine only.

Note

The XC0 topology for developer workstation does not include container images for the SXA storefront or supporting modules.

For a deployment that includes the modules required to support the SXA storefront, you must install the XC1-CXA topology.

xc1

Contains files used to build Sitecore XC1 topology images. The XC1 topology is for a scaled deployment that excludes modules supporting the SXA Storefront. You use this topology in a scaled, Commerce Engine only deployment, that does not use the SXA Storefront.

Note

The Sitecore Commerce Container SDK does not include all Docker compose YAML files required to deploy the container images of the XC1 topology.

xc1-cxa

Contains files necessary to build and run a Sitecore XC instance in a XC1 topology. This deployment topology includes the SXA Storefront.

xc-common

Contains files necessary to build common Sitecore XC images.

Note

Common images are used by all Sitecore XC topologies.

The xc-common folder

The xc-common folder contains all files necessary to build Sitecore XC images common to all default deployment topologies included in the SDK.

Following is an example of the xc-common folder structure:

The [service] folder

Each of the [service] folders:

  • Represents a container

  • Contains at minimum a Dockerfile.

  • Is used as the Docker build context for the corresponding service in the Docker Compose file.

The Docker compose build YAML file

The docker-compose.build.yml file defines images build for the following services, used in both XC0 and XC1 deployment topologies:

Note

Images in this folder have to be build before images located in the xc0 , xc1, and xc1-cxa folders.

  • id

  • bizfx

  • engine

The xc0 folder

The xc0 folder contains all the files necessary to build and run Sitecore XC0 topology images.

The following shows an example of the xc0 folder structure:

The [service] folder

Each of the [service] folders:

  • Represents a container.

  • Is used as the Docker build context for the corresponding service in the Docker Compose file.

The docker compose build YAML file

The docker-compose.build.yml file defines images build for the following services:

  • mssql non-production

  • solr non-production

  • cm

  • xconnect

  • xdbsearchworker

  • xdbautomationworker

The docker-compose.yml contains information about all containers required for a XC0 instance.

The xc1 folder

The xc1 folder contains all files necessary to build XC1 topology images.

The following shows an example of the xc1 folder structure:

The [service] folder

Each of the [service] folders:

  • Represents a container.

  • Is used as the Docker build context for the corresponding service in the Docker Compose file.

The docker compose build YAML file

The docker-compose.build.yml file defines images build for the following services:

Note

Images in this folder have to be build before images contained in the xc1-cxa folders.

  • mssql non-production

  • mssql-init

  • solr non-production

  • solr-init

  • rep

  • xdbcollection

  • prc

  • cm

  • cd

  • xdbsearch

  • xdbsearchworker

  • xdbautomation

  • xdbautomationworker

The xc1-cxa folder

The xc1-cxa folder contains all files necessary to build and run XC1 topology images, including the SXA storefront.

The following shows an example of the xc1-cxa folder structure:

The [service] folder

Within the xc1-cxa folder, each of the [service] folders:

  • Represents a container.

  • Contains at minimum a Dockerfile.

  • Is used as the Docker build context for the corresponding service in the Docker Compose file.

The Commerce build YAML file

The commerce.build.yml file defines Commerce images build for the following services.

The docker compose build YAML file

The docker-compose.build.yml file defines images build for the following services:

The docker compose YAML file

The docker-compose.yml file contains information about all containers required for a XC1 instance.

The Scripts folder

This scripts folder contains a set of support scripts and JSON files that facilitate the creation of the Sitecore Experience Commerce container images using Docker.

The following table lists and briefly describes the content the of scripts folder.

Note

Refer to the readme.md file included within the script folder for more details. Script files themselves are also commented with additional information and guidance.

File

Description

CleanContainerCache.ps1

Script used to clean the Docker container images cache. The container images cache is used to speed any action that requires container images to be pulled from a registry. Examples of Docker commands that use the container images cache include : docker pull, docker-compose up, docker-compose build.

ContainerBuild.ps1

Script used to build container images based on the contents of the docker-compose.build.yml files. The results are container images with the tag "latest".

ContainerTag.ps1

Script used to tag container images based on the provided tag value.

PrepContainerBuild.ps1

Script that takes the Sitecore Experience Commerce Release Package artifacts and expands them into the source code directory structure.

UpdateEnvTag.ps1

Script that sets the container image registry, namespace, project and tag of container images.

UpdateEnvCompose.ps1

Script that updates a /[topology]/.env file with provided values.

UpdateK8SYaml.ps1

Script that sets Kubernetes secrets files with values from the configltsc2019.json file. Kubernetes is only supported in a Windows LTSC 2019 environment.

ScriptSupport.psm1

Script that contains supporting functions used by other script files.

WDPMapping.json

File used by the PrepContainerBuild.ps1 script. This file contains mapping information that is used to place the content of the release package artifacts in the correct location to be use when running the docker-compose build command.

configltsc2019.json

and

config1909.json

Files used by the update scripts UpdateEnvTag.ps1, UpdateEnvCompose.ps1, and UpdateK8SYaml.ps1 to override or replace tokens in the .env and yml files. This allows the files to be customized for use in the build and run processes.

FakeLicenseFile.txt

File that contains a fake license.

WDPs mapping

The WDPMapping.json file contains mapping information that is used to place the WDP packages that are part of the Sitecore XC release package in the appropriate folder structure for use by the Docker compose build process.

The WDPMapping.json is used by the PrepContainerBuild.ps1 script.

In the following mapping example, the content of the "Content/Website" folder within the listed WDPs packages will be copied to the destination folder xc1-cxa/cd/wdp within the Sitecore.Commerce.Container.SDK folder.

Note

The WDPMapping.json lists WDPs with similar names starting with the the WDP with the most exclusive package name, and ending with the least exclusive package name.

{
  "WDPs": [
      "Sitecore Commerce Experience Accelerator Storefront Themes",
      "Sitecore Commerce Experience Accelerator Storefront",
      "Sitecore Commerce Experience Accelerator"
  ],
  "DestinationFolder": "xc1-cxa/cd/wdp",
  "ToCopyFolder": "Content/Website"
}

In the following example, the .dacpac files in the listed WDP packages are copied to the destination folder xc1-cxa/mssql/dacpacs within the Sitecore.Commerce.Container.SDK folder. The .dacpac files matching the names master, core or web will be renamed to Sitecore.Master, Sitecore.Core and Sitecore.Web respectively, in the destination folder.

{
  "WDPs": [
      "Sitecore Commerce Experience Accelerator Habitat Catalog",
      "Sitecore Commerce Experience Accelerator Storefront Themes",
      "Sitecore Commerce Experience Accelerator Storefront",
      "Sitecore Commerce Experience Accelerator"
  ],
  "DestinationFolder": "xc1-cxa/mssql/dacpacs",
  "ToCopyFiles": "*.dacpac",
  "NameMappings":  [
      {"Name":"master", "NewName":"Sitecore.Master"},
      {"Name":"core", "NewName":"Sitecore.Core"},
      {"Name":"web", "NewName":"Sitecore.Web"}
  ]
}
If you have suggestions for improving this article, let us know!