Sitecore Commerce 10 for Developer Workstation with Containers

Over the last couple of days, have been trying to setup Sitecore Commerce 10 on Docker (XC0 topology). First of all, I'm totally in love with this new Sitecore 10 feature of Sitecore and Docker integration. I can't stop raving about this step forward by Sitecore. The setup is so easy and the footprint is so much lesser compared to earlier installations. Forget about the pre-requisites like setting up IIS, SQL Server etc., you don't need to install Vanilla Sitecore. One docker-compose up command does the job of setting up the Commerce instance. What a master step by Sitecore!

So, with this excitement I tried to setup Sitecore Commerce 10 on Docker. The installation was fairly smooth. I then performed the necessary bootstrapping, sync, initialize etc., but hit a roadblock thereafter since I couldn't find a way to access the store front or create a store front in the content tree. I dived deeper and compared the DB sizes generated for this installation with earlier Commerce installation and I could find notable difference. Also, I couldn't find any traces of SXA installed in the Master DB for the Sitecore instance running on Docker. So, have raised a ticket and waiting for response. If someone reading this blog has been successful with Commerce installation on Docker, please add your thoughts in the comments section. From my side, will update the blog if I make any progress.

Sitecore XC10 DB instance running on Docker:

---------------------------------

For now, just blogged my approach here:

Pre-requisites:

a. Minimum 16 GB RAM: Chose a VM with 32 GB RAM

b. Windows 10 or Windows Server, 1809 or later: Chose a VM with Windows 10 Pro

A snapshot of hardware requirements:

c. Download and install Docker Desktop for windows

d. Sitecore Commerce Container SDK

Installation Steps:

1. Unzip pre-requisite d onto a folder say, c:\sitecore -

Based on the topology, the folder needs to be picked. Since we are performing installation for local development, XC0 is the folder that must be used. 

2. The next step is to fill the environment variables. Take a look at Auto-Fill the .env file for Sitecore XC 10 Docker Container Installation (XC0  topology)

3. Once the env variables are ready, open cmd prompt in Administrator mode and execute docker-compose up -d 

4. The docker services must display done status one after another and the cmd prompt must return. The below screen shot shows the cmd prompt and the docker dashboard opened side-by-side -

5. Wait until docker-compose ps returns healthy for all service status. They are usually "Health: Starting" or sometimes "Unhealthy" and then change status on re-run of docker-compose ps:

Note that redis, solr and traefik are ok to be just Up and don't need to be Up (healthy).

6. Open mssql-data folder in c:\containers and check  the size of SitecoreCommerce_Global and SitecoreCommerce_SharedEnvironments DBs. The size of these DBs will increase after boostrapping (down the line) -

7. The CM url should return the default Sitecore page:

8. Open the content editor based on the password passed through the script, Password12345 in my case. Note that there is no option to create a tenant. Also, Project folder under templates will be empty.

9. Go to Sitecore Commerce 10 downloads page and download the Packages for On Premise WDP 2020.08-6.0.238

10. Unzip the package and unzip Sitecore.Commerce.Engine.SDK.6.0.130.zip within the package to find the postman folder:

11. Download Postman, open Postman and click the import button on top left corner, Click the Folder tab and select the postman folder -

12. Confirm your import:

13. APIs loaded:

14. Next, we need an environment to execute the APIs but no environments present currently:

15. Let's import environments next by clicking the cogwheel in the top right corner and press the grey Import button in the window that pops:

16. Choose the environment json files from postman folder:

17. The environments will be listed in the subsequent window, just close the window:

18. Environments populated in the top right drop down:

19. Ensure SSL is switched off in the settings window:

20. Next step is to set the environment variables, Click on the cog wheel again to see the environment window, click on habitat environment:

21. The click must display the list of pre-populated environment variables:

22. Based on .env file values, add the host names:

.env file values:

23. Time to execute the APIs, the first step is to get  a  valid token before accessing other APIs. So, execute, GetToken API by selecting Habitat Environment in the top right, clicking the API in the left pane and press send button:

22. If your identity server host name is correct, you must get an access token like this:

23. Next step is to bootstrap the commerce environment. The API is under Sitecommerce_Devops as highlighted in the screen shot below, select the API and press send  -

Note that the api host name is all passed through the environment variables. So, if that is set fine, the call will execute successfully.

24. Bootstrapping should be successful if all settings are fine:

25. Next execute Ensure\Sync default content paths:

Note that the response code is 200 but the status in the response body is WaitingForActivation.

26. To check if the API is successfully executed, pick up the task id, which is 1 based on above screen shot and execute Check Long Running Command Status  by passing 1 in the address bar:

Understandably, the task id will change for you based on the response returned by the Ensure\Sync default content paths API. Also, you will have to be patient enough and execute the above Check Long Running Command Status API a few times to see if the Ensure\Sync content default paths API RanToCompletion!

27. Curious me, just switched over to the mssql-data folder to check if there is any change in size of Commerce DBs and yes, the SitecoreCommerce_SharedEnvironments_Primary DB has changed size due to successful bootstrapping:

28. The next step is to initialize the environment by executing the Initialize Environment API:

29. And, this time, you know what to do when the status is WaitingForActivation. Execute Check Long Running Command Status API to check the task status by passing the correct task id, which is 1 again (but understandably, the id  need not be 1 every time):

Note that I had to point the address to OpsApiHost environment variable in the above case since Initialize Environment points to OpsApiHost environment variable. So, every time you check the task status of an API ensure that the host name is same and correct as the API that you are checking the status of.

30. Perform a restart of Minions, Authoring, CM and and Shop services through Docker dashboard:

31. Back in Postman, perform Full Index of Catalog Items, the API is named Run FullIndex Minion - Catalog Items:

Check status of completion using Check Long Running Command Status of Minions by passing the above task id.

32. Similarly, Run the following APIs:

a. Run FullIndex Minion - Promotions

b. Run FullIndex Minion - Price Cards

33. Next, let's invoke Catalog (Habitat),  gives an assurance that Habitat catalog is present:

31. Bizfx and content editor should still load fine:

32. In the content editor, click refresh commerce cache. The option is under Caches and can be picked from My ToolBar -> Customize 

33. Next, click Update Data Templates (can be picked from Customize and selecting Catalog tile)

No change in the content tree or any option to create a tenant after this. Waiting to complete!

Common Errors:

Error: .\init-setup.ps1 : File C:\sitecore10\Sitecore.Commerce.Container.SDK.1.0.214\xc0\init-setup.ps1 cannot be loaded

because running scripts is disabled on this system. For more information, see about_Execution_Policies at

https:/go.microsoft.com/fwlink/?LinkID=135170.

At line:1 char:1

+ .\init-setup.ps1 c:\license\license.xml

+ ~~~~~~~~~~~~~~~~

    + CategoryInfo          : SecurityError: (:) [], PSSecurityException

    + FullyQualifiedErrorId : UnauthorizedAccess

Context and Solution: This happens when you open Powershell  for the very first time and try to execute init-setup.ps1. Run  set-executionpolicy remotesigned

Error: Get-InstalledModule : A parameter cannot be found that matches parameter name 'AllowPrerelease'.

At line:1 char:73

+ ... itecoreDockerTools -RequiredVersion '10.0.5' -AllowPrerelease -ErrorA ...

+                                                  ~~~~~~~~~~~~~~~~

    + CategoryInfo          : InvalidArgument: (:) [Get-InstalledModule], ParameterBindingException

    + FullyQualifiedErrorId : NamedParameterNotFound,Get-InstalledModule

Context and Solution: This happens when you run Get-InstalledModule command. Note that Get-InstalledModule is part of init-setup.ps1. The solution is to execute the following commands one after another:

Install-Module -Name PackageManagement -Repository PSGallery -Force

Install-Module -Name PowerShellGet -Repository PSGallery -Force

Then, restart Powershell and retry Get-InstalledModule.

Error: ERROR: for xc0_engine-authoring_1  Cannot start service engine-authoring: container d522383158ed990509363166fd4f09d5870764008f1f37b5bc8d94938d41fee1 encountered an error during hcsshim::System::Start: context deadline exceeded

ERROR: for engine-authoring  Cannot start service engine-authoring: container d522383158ed990509363166fd4f09d5870764008f1f37b5bc8d94938d41fee1 encountered an error during hcsshim::System::Start: context deadline exceeded

ERROR: Encountered errors while bringing up the project.

Context and Solution: This happens when you docker-compose up. I suspect this is due to some kind of locking or a race condition. Frankly, need to understand the cause better since this can happen with any of the services. I follow this as a temporary solution:

Perform docker-compose down, ensure Docker dashboard is clear. Optionally, Delete msql-data and solr-data folders under c:\containers. Restart machine and retry docker-compose up. I do this when the concerned service has run fine in the past but didn't go through this time and I'm sure my env variable values (and, the docker compose file) are correct and unhampered.

Error: ERROR: for xc0_engine-minions_1  Cannot start service engine-minions: container c244a1cc2aaca70394a3ca68daba0f021bb9f4dea86b166560fbce54e55fd91d encountered an error during hcsshim::System::Start: context deadline exceeded

ERROR: for engine-minions  Cannot start service engine-minions: container c244a1cc2aaca70394a3ca68daba0f021bb9f4dea86b166560fbce54e55fd91d encountered an error during hcsshim::System::Start: context deadline exceeded

ERROR: Encountered errors while bringing up the project.

Context and Solution: This happens when you docker-compose up. I suspect this is due to some kind of locking or a race condition. Frankly, need to understand the cause better since this can happen with any of the services. I follow this as a temporary solution:

Perform docker-compose down, ensure Docker dashboard is clear. This is how a clear dashboard looks if you had only one container running:

Optionally, delete msql-data and solr-data folders under c:\containers. Restart machine and retry docker-compose up. I do this when the concerned service has run fine in the past but didn't go through this time and I'm sure my env variable values (and, the docker compose file) are correct and unhampered.

ERROR: open \\.\pipe\docker_engine_linux: The system cannot find the file specified.

Context and Solution: Happens when you run docker-compose up -d for the first time after installing Docker for windows. Right click the whale icon in task bar and Switch to Windows containers.

ERROR: Pulling mssql (scr.sitecore.com/sxc/nonproduction/sitecore-xc0-mssql:10.0.0-ltsc2019)...

ERROR: Get https://scr.sitecore.com/v2/: x509: certificate signed by unknown authority

Context and Solution: Happens when you run docker-compose up -d for the first time after installing Docker for windows. Right click the whale icon in task bar and Switch to Windows containers.

ERROR: Unable to start Hyper-V VM: 'DockerDesktopVM' failed to start.

Context and Solution: Happens when Docker is trying to start and the whale turns red throws a fatal exception. The reason this happened was, I initially had installed the Docker desktop on 32-GB RAM VM and then switched size to 16 GB RAM VM. Somehow, Docker didn't like this and so, when i switched back to 32 GB RAM with 4 vcpus, this error didn't occur.

References:

https://github.com/MicrosoftDocs/OfficeDocs-SkypeForBusiness/issues/3094

https://www.faqforge.com/windows/windows-powershell-running-scripts-is-disabled-on-this-system/

Installation Guide: https://dev.sitecore.net/~/media/AC4B8DFC9F3D464BA23EFD553F95BF33.ashx 

https://dev.sitecore.net/Downloads/Sitecore_Commerce/100/Sitecore_Experience_Commerce_100.aspx