Setup local XM Cloud development environment using Docker containers

In my previous blog, I explained how we can set up the XM cloud locally without docker where the Next.js application is directly connected to the XM cloud application through the Experience Edge endpoint. This set-up was good enough for front-end application developers but in Sitecore connected mode development, full set-up is required on the development machine. Here, in this blog, I will explain how to set up a local XM Cloud development environment (Next JS application + Sitecore XM) using Docker containers.

Prerequisites

• Install .Net SDK 6.0 and runtime – You can install it from here. Installing a .Net SDK will include the corresponding runtime and does not require a separate installation. You can check to see if you already have .Net SDK 6.0 installed by executing dotnet --info command in your terminal.
• .NET Framework 4.8 SDK
• Docker for Desktop with Windows Containers enabled – see all the installation requirements for Docker Containers here
• Node LTS – You can install it from here. Should be at least v18.13.0
• PowerShell 5.1
• Hyper-V enabled from within Turn Windows features on or off.
• Create an account on https://portal.sitecorecloud.io/. – If you already have access to the XM Cloud portal and are part of the organization, then you can skip this. Otherwise, if you don’t already have an account on the cloud portal, just register yourself. Even if you don’t yet have an organization, create an account. Logging in here is how you will log in to your local environment regardless if it is tied to an organization or not.

Set up Steps:

1. Clone the GitHub repository on your local machine (I have cloned it at C:\sitecore\xmcloud path): https://github.com/sitecorelabs/xmcloud-foundation-head
2. Place a valid Sitecore license file in the C:\License folder.
3. Open PowerShell and cd to the folder where you have checked out the code. (cd C:\sitecore\xmcloud path).
4. Now run: .\init.ps1 -InitEnv -LicenseXmlPath "C:\License\license.xml" -AdminPassword "b"

5. Run setx NODE_EXTRA_CA_CERTS C:\Users\SitecoreAdmin\AppData\Local\mkcert\rootCA.pem

6. Close the PowerShell window and reopen it. Again, CD to the same folder.

7. To download the Sitecore Docker images, install and configure the containers and client application, run the following script: .\up.ps1

8. If it’s successful, you will see the following Device Confirmation screen.

9. Once confirmed you will then be asked to log in to the XM cloud portal.

10. After you log in to the portal, you will see this successful message in CLI. It will then populate the schema and build the indexes.

This is it. Now you will see, your localhost website opening in your browser:

Troubleshoot:

1. While trying to spin up the xmcloud-foundation-head locally in containers and getting into this error: Waiting for CM to become available. Invoke-RestMethod : Unable to connect to the remote server. Invoke-RestMethod "http://localhost:8079/api/http/routers

Solution: Ensure that the “Use Docker Compose V2” option is not checked and Use the WSL 2 based engine is checked.

Make sure that IIS is stopped and you don’t have SOLR and  SQL Server instances running.

Then Down the docker and clear all Docker data using the below commands:

.\down.ps1

cd docker

./clean.ps1

Then Run the containers again using .\init.ps1 and .\up.ps1

2. If you get this error: ERROR: Service 'nodejs' failed to build : Build failed

Solution: This issue is due to firewall settings and network policy settings on your development machine.

• Try to flush the DNS on your local and run the set-up again. In the command prompt window, type ipconfig /flushdns You should see a message confirming that the DNS Resolver Cache was successfully flushed.

• Another thing you can try is to add custom DNS to the Docker engine config file. You can use Google DNS- 8.8.8.8 as mentioned here.
• If none of the above options works, install nodejs manually.
  • Create an empty folder eg. C:/tempfolder. Open CMD and run cd C:/tempfolder.
  • Run this command in CMD curl.exe -sS -L -o node.zip https://nodejs.org/dist/v16.15.1/node-v16.15.1-win-x64.zip
  • Then Run tar.exe -xf node.zip -C C:\
  • Now Run move C:\node-v16.15.1-win-x64 c:\node
  • Run del node.zip
  • In the above command, I have taken 16.15.1 based on the NODEJS_VERSION parameter set in .env file.
  • Comment below lines in Dockerfile, available in ROOT_PROJECT/docker/build/nodejs/Dockerfile

#RUN curl.exe -sS -L -o node.zip #https://nodejs.org/dist/v%NODEJS_VERSION%/node-v%NODEJS_VERSION%-#win-x64.zip
#RUN tar.exe -xf node.zip -C C:\
#RUN move C:\node-v%NODEJS_VERSION%-win-x64 c:\node
#RUN del node.zip

• Now run the set-up again.

Set up front-end application:

1. Cd src/sxastarter folder

2. Run jss setup

3. If the jss command is not available, install it using the command npm install -g @sitecore-jss/sitecore-jss-cli

4. Once you will run jss setup command, you need to answer a few configuration-related questions, have a look at the below screenshot. To get the Sitecore API Key, go to CMS and navigate to this path (/sitecore/system/Settings/Services/API Keys/xmcloudpreview). XM Cloud environment is pre-configured with the GUID {1C8CF303-D973-4D40-811B-D3297D4643F2}. So we will use that one.

5. This step will generate the scjssconfig.json file, which looks like this:

6. Now we will create a headless tenant and a headless site with the name of the JSS app. You can find the name of the JSS app in the package.json file:

7. In the content editor create a headless tenant

8. Create a headless site

9. Run npm install to prepare the app, and then run npm run start:connected to start the app in Sitecore-connected mode.

10. The app should now be available on https://www.sxastarter.localhost/. If you browse to this URL you will get the following error:

11. This error can be solved by configuring a root item ID. This root item ID must be configured in the file: \src\lib\dictionary-service-factory.ts. The GUID to be used is the template ID of the home item of your JSS app:

12. And again we get an error:

The local XM Cloud environment will not be connected to CDP, so for now we comment out the CdpPageView in the src\Scripts.tsx file:

14. Now open the home page in the Experience Editor and we can edit the page!

15. Down the containers

Happy Sitecore XM Cloud developing 🙂