Workflow for creating custom Commerce container images
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:
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.
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
-
Open the
Sitecore.Commerce.Container.SDK.*.*.***/scripts/WDPMapping.json
. -
Remove the sample Commerce Engine WDP:
RequestResponseshell{ "WDPs": [ "Sitecore.Commerce.Engine.OnPrem.Solr" ], "DestinationFolder": "xc-common/engine/wdp", "ToCopyFolder": "Content/Website" }
-
If you have customized the XC Business Tools, you should also remove the following section containing the mapping to the
Sitecore.BizFx.OnPrem
package:RequestResponseshell{ "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, that is config2019.json
or configltsc2019.json
To add your custom image tags to the configuration:
-
Open the appropriate JSON file based on the OS running on the host, that is
config2019.json
orconfigltsc2019.json
. -
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/
NoteYou must create the wdp folder.
-
Add your Business Tools customization to the folder:
xc-common/engine/bizfx/wdp
NoteYou 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
NoteWhen 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 theinetpub/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 thecontent/website/
folder (for examplexc0/cd/content/website/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 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:
RequestResponseshellUpdateEnvTag.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:
-
Download the following Sitecore Experience Commerce release packages from the Sitecore Downloads site:
-
Packages for On Premise WDP ****.**.**-*.*.***
-
Packages for Azure App Service ****.**.**-*.*.***.
NoteThe
PrepContainerbuild.ps1
script that is used to prepare the container build includes references to WDPs within these release packages. -
-
To get the container images, open a PowerShell window, and run the following command:
RequestResponseshellPrepContainerbuild.ps1 -jsonFile 'C:\sitecore-commerce\scripts' -releaseZipPath 'C:\downloads'
Build your container images
To build your container images:
-
Open a PowerShell window, and run the following command:
RequestResponseshellContainerBuild.ps1 -envRootPath 'C:\sitecore-commerce'
-
Confirm that the images were created by listing all Docker images:
RequestResponseshelldocker images