Sitecore Commerce Container SDK

Abstract

Describes the content of Sitecore Experience Commerce container software development kit.

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.

postman

Contains sample sets of Postman environment files (in JSON format), to use with Commerce deployment running in Docker or Kubernetes.

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.

Upgrade

Contains configuration and environment files used to upgrade Sitecore XC database content.

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.

The following shows an example of the xc-common folder structure:

```
+ xc-common
    + [service]
       + Dockerfile
       + [...]
    + .env
    + docker-compose.build.yml
```

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:

```
+ xc0
    + [service]
        + [...]
    + [...]
    + .env
    + docker-compose.build.yml
    + docker-compose.yml
```

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:

  • solr-init

  • 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:

```
+ xc1
    + [service]
         + [...]
    + [...]
    + .env
    + docker-compose.build.yml
```

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

  • mssql-init

  • solr-init

  • solr-init-searchstax

  • 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:

```
+ xc1
    + [service]
        + [...]
    + [...]
    .env
    commerce.build.yml    
    docker-compose.build.yml
    docker-compose.yml 
```

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

ComposeInit.ps1

Script used to initialize a Windows Docker environment, such that the environment is quickly prepared and ready for a Docker deployment.

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.

PrepEngineContainerBuild.ps1

Script that takes the Commerce.Engine.OnPrem.Solr and Sitecore.BizFx.OnPrem WDP's and expands the contents into the structure expected by the Sitecore XC container Docker file.

UpdateEnvTag.ps1

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

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.

UpdateK8SUpgradeYaml.ps1

Script that is used to update secrets files for a container upgrade scenario. Kubernetes is only supported in a Windows LTSC 2019 environment.

configltsc2019.json

config20H2.json

config2009.json

Files used by the UpdateEnvTag.ps1, ComposeInit.ps1, and UpdateK8SYaml.ps1 scripts 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.

readme.md

A readme file that contains details about the provided scripts.

The upgrade folder

The upgrade folder contains the necessary docker and Kubernetes files that you can use to upgrade Sitecore XC content.

The following shows an example of the upgrade folder structure:

+ upgrade
    + k8s-sitecore-xc1
        + configuration
            + [...]
        + kustomization.yaml
        + mssql-upgrade.yaml
    + sitecore-xc
        + docker-compose-upgrade.yml
        + upgrade.env
```

The k8s-sitecore-xc1 folder

The k8s-sitecore-xc1 folder contains the Kubernetes files for the Sitecore XC upgrade.

The following table lists and briefly describes the contents the of k8s-sitecore-xc1scripts folder:

File

Description

mssql-upgrade.yaml

The Kubernetes specification file that you use to deploy, configure, and run the upgrade container in a Kubernetes cluster.

kustomization.yaml

The file that deploys all the secret names and values required by the upgrade container.

The ks8s-sitecore-xc1/configuration folder

The ks8s-sitecore-xc1/configuration folder contains the secrets and ConfigMap files. These text files store Kubernetes secrets and ConfigMap values used by the upgrade container.

The sitecore-xc folder

The sitecore-xc folder contains the docker compose files used for the Sitecore XC upgrade.

The following table lists and briefly describes the files within the sitecore-xc folder:

File

Description

docker-compose-upgrade.yaml

The docker compose file used to upgrade Sitecore XC Mssql containers.

upgrade.env

The environment file that contains the variables used for the upgrade.