Sitecore XM Cloud - possible issues when starting Docker

I had this blog post in draft for a while since I didn't feel like it brought enough to the table. But, I wanted to have another blog post out for closing the Sitecore MVP application season too.

Some of the items are just my own fault when trying to start a local environment when its not configured properly. However, maybe it could help out some others who encounter the same.

1. Unable to connect to the remote server

The up.ps1 contains a step to wait until the CM container is up & healthy. If you get this error, there was an error on the CM-container that prevents it from booting.

Solution:

Open docker desktop and open the related container to access its logs. In my case, I had a nice error saying my license file was missing and Sitecore rebooted.

2. Container build failed - Invalid template

This error was also logged when running up.ps1.

In my case, the init.ps1 script added a number of automatically-generated tokens to the .env file. (These will differ per environment)

REPORTING_API_KEY=EqXRkfrrldE6pkgXUUOUgjpS1EPqQ2AIhYWprQemfvzFXhok92HMOkqG1krZ8qXGnHa6Dv9t3H9T5uCk7N4wqF8HCs9mxcN4cTrNbMMSeSLQtVtR3VQxnTuW15hEKT5q
TELERIK_ENCRYPTION_KEY=*^[J$$[ljUbiPrt0L^+vG4z@K&w\_F$$>^VbV6AXRTYgUlYh(w148o60o6Ezl{:lZhwDvWiQJ8}>^wQJCaex+Bu0]q.RT:?6wMALwW_)l!2cd5;)qwAJO%2]6r.vro&]GP
MEDIA_REQUEST_PROTECTION_SHARED_SECRET=(cfiz`#-&2dD1l]w:f+bdoXEwlh^\b*JAe_y+M!%jGcQ~0U(5Dc{[(~+k9Kx6)q|

Unfortunately, one of those keys/secrets contained a $ char that wasn’t properly escaped. My docker (desktop) version contained a bug/feature that requires $ chars to be escaped with another $ to be valid.

Solution

Replace any $ with $$ in your .env to ensure they’re properly escape. Save your changes and rerun up.ps1

3. Up.ps1 fails - issue #1: no internet connection from within docker

When you run up.ps1, you get the following error after a few minutes

Waiting for CM to become available... Created                                                                      0.1s
Invoke-RestMethod : Unable to connect to the remote server                                                         0.1s
At C:\vs\xm-cloud-playground\up.ps1:59 char:19                                                                     0.1s
+ ...   $status = Invoke-RestMethod "http://localhost:8079/api/http/routers ...

If you open the CM container’s logs (using docker desktop’s UI), you’ll only notice Sitecore reboots intermittently

1964 15:15:23 WARN  Sitecore shutting down
1964 15:15:23 WARN  Shutdown message: Initialization Error
HostingEnvironment initiated shutdown

This doesn’t explain what’s happening, so open a terminal window to the container - easiest done from within Visual Studio. If you then look at the inetpub logs, you’ll notice the requests to the healthcheck result in a HTTP500 error

2023-08-24 12:45:29 ::1 GET /healthz/ready - 80 - ::1 Mozilla/5.0+(Windows+NT;+Windows+NT+10.0;+en-US)+WindowsPowerShell/5.1.17763.4720 - 500 0 0 25613

Unfortunately, this doesn’t tell us anything - only that the healthprobe gives a YSOD. So execute the following command in that container’s terminal window to see the page’s exact markup

curl http://127.0.0.1/healthz/ready

The detailed error was in this case

[WebException]: The remote name could not be resolved: 'auth.sitecorecloud.io'
   at System.Net.HttpWebRequest.EndGetResponse(IAsyncResult asyncResult)
   at System.Net.Http.HttpClientHandler.GetResponseCallback(IAsyncResult ar)

which reveals no internet connection is possible on the docker container.

Solution:

As described on Troubleshooting Docker | Sitecore Documentation :

This often happens when there are multiple networking adapters (Ethernet, Wi-Fi) present on the host. You must set the priority of these adapters properly in order for the Windows networking stack to correctly choose gateway routes. You can fix this by setting your primary internet-connected networking adapter to have the lowest InterfaceMetric value:

Execute the following command on your hosting machine to get all network adapters ordered by priority:

Get-NetIPInterface -AddressFamily IPv4 | Sort-Object -Property InterfaceMetric -Descending

In my case the host was connected with a UTP cable, which had a low priority. After modifying the priority (lower = better) using the following command, the container would work again

Set-NetIPInterface -InterfaceAlias 'Ethernet 2' -InterfaceMetric 1

4. Up.ps1 fails - issue #2: invalid mount config for type “bind”

Check your .env file for the HOST_LICENSE_FOLDER configuration.
This one should be set correctly to the folder that contains your valid Sitecore license.xml file.

It should not point to the license file directly: C:\Siteocore License\license.xml

Solution:

Double check the location of your license.xml file and hook it up to the correct folder in your .env file.