Setup Sitecore XM Cloud Dev Environment using Docker

In this blog, I will walk you through the process of setting up a Sitecore XM Cloud development environment using Docker containers.

What is XM Cloud?

Sitecore Experience Manager Cloud (XM Cloud) is a completely managed self-service deployment platform designed for developers and marketers, enabling them to seamlessly launch compelling omnichannel experiences in the Cloud utilizing Sitecore's headless CMS capabilities.

Docker Containers -

On the other hand, Docker containers enable the creation of a local environment that closely replicates the production setup. Sitecore offers pre-configured container images, making it simple to set up. By using  "docker-compose up", you can swiftly launch an instance, and the required container images will be downloaded automatically.

Let's dive in and get started!

Prerequisites -

Before we start setting up the Sitecore XM Cloud, ensure that you have the following prerequisites ready and installed:

• A valid Sitecore License file.
• .Net SDK 6.0 and runtime, which you can download and install from here. 
• .NET Framework 4.8 SDK.
• Docker for Desktop with Windows Containers enabled.
• Node LTS, which you can download and install from here. The minimum required version is v18.13.0.
• PowerShell 5.1
• Hyper-V enabled from within the 'Turn Windows features on or off' option.
• An account on https://portal.sitecorecloud.io. If you already have access to the XM Cloud portal and are part of an organization, you can skip this step. Otherwise, register yourself even if you don't have an organization yet. You'll need to log in to your local environment using this account.

Set up Steps -

After ensuring that you have all the prerequisites in place, it's time to spin up the Docker containers. Follow these steps:

• Clone the Sitecore XM Cloud repository from GitHub to your local machine. You can clone it to a directory of your choice. For example, C:\Project\xm-cloud directory.
• Place a valid Sitecore license file in the C:\License folder.
• Open PowerShell in admin mode and navigate to the directory where you cloned the XM Cloud repo i.e. cd C:\Project\xm-cloud path.
• Run the following command in PowerShell:

Enable-WindowsOptionalFeature -Online -FeatureName containers –All

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V –All

iisreset /stop

.\init.ps1 -InitEnv -LicenseXmlPath "C:\License\license.xml" -AdminPassword "b"

• In case, if you encounter this error while running the above script. Set the scripts execution policy in PowerShell to proceed further.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

• Once the command completes successfully, you'll see a message on the PowerShell window indicating that you need to set the NODE_EXTRA_CA_CERTS environment variable to avoid HTTPS errors. Copy the command provided in the message and run it on your terminal.

• Close the PowerShell window and reopen it. Now, CD to the same project folder.
• To download the Sitecore Docker images, install and configure the containers and client application, run the following script:

.\up.ps1

When successful, you'll get the Device Confirmation screen on your browser. Confirm this to proceed with the next steps.

• Once confirmed you will then be asked to log in to the XM cloud portal.
• 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.
• Once all processes are done successfully, you will get your local site opening on your browser.

At this point, we have successfully installed XM Cloud on our local environment using Docker Container.

Set up front-end application:

Once you've successfully set up the XM Cloud on your local environment, the next step is configuring the front-end project. Follow the steps below:

• Open PowerShell in Admin mode and navigate to the src\sxastarter folder where you have the SXA starter project.
• jss command needs to be installed. Install it using the following npm command.

npm install -g @sitecore-jss/sitecore-jss-cli

• Now run jss setup command.
• After running the "jss setup" command in the "src\sxastarter" folder, a few configuration-related questions will be prompted.
• To obtain the Sitecore API Key, go to the CMS and navigate to this path: "/sitecore/system/Settings/Services/API Keys/xmcloudpreview".

• The file scjssconfig.json is generated by the jss setup command, and it looks like:

{
  "sitecore": {
    "instancePath": "C:\\inetpub\\wwwroot",
    "apiKey": "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}",
    "deploySecret": "*******************",
    "deployUrl": "https://xmcloudcm.localhost/sitecore/api/jss/import",
    "layoutServiceHost": "https://xmcloudcm.localhost"
  }
}

XM Cloud project setup in local Sitecore to deploy our JSS app

Before deploying the JSS app, we need to prepare the XM Cloud environment by creating a headless tenant and a headless site with the name of the JSS app. 

• The name of the JSS app can be found in the "package.json" file.

• Login to Sitecore and create the Headless Tenant and Site.

• Create a headless site. Make sure, Site name is same as highlighted above in the package.json file.

• Go to Site Settings tab and use the Deployment secret from the scjssconfig.json file.

• Once the site is created run the below command to push the serialized items to Sitecore which includes the rendering items.

dotnet sitecore ser push

Starting the app 

Finally, it's time to start your app and see it in action. Follow the steps below:

• Open Rendering project i.e. src\sxastarter in VS Code.
• Run "npm install" or "npm i" in your VS Code terminal. This will install all the node modules dependencies required for this project.
• Now, run "npm run start:connected" to start the app in Sitecore-connected mode.
• The app should now be available on https://www.sxastarter.localhost/ and on http://localhost:3000/
• Now open the home page in the Experience Editor and we can edit the page!

Troubleshooting:

Here are some troubleshooting tips which I have encountered during setup.

ERROR: Service 'nodejs' failed to build : Build failed

SOLUTION: This issue is due to firewall settings and network policy settings on your development machine. Bypass some common network issues by setting DNS servers in the Docker engine configuration. Try to add this in your Docker configuration.

{
  "debug": false,
  "dns": [
    "8.8.8.8"
  ],
  "experimental": true,
}

ERROR: .ps1 is not digitally signed. The script will not execute on the system.

SOLUTION: To fix it you have to run the command below to run Set-ExecutionPolicy and change the Execution Policy setting.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

ERROR: Sqlcmd: Error: Microsoft ODBC Driver 17 for SQL Server : Named Pipes Provider: Could not open a connection to SQL Server [2]. . Sqlcmd: Error: Microsoft ODBC Driver 17 for SQL Server : Login timeout expired. Sqlcmd: Error: Microsoft ODBC Driver 17 for SQL Server : A network-related or instance-specific error has occurred while establishing a connection to SQL Server. Server is not found or not accessible.

SOLUTION: There are two possible reasons. 

1. Firewall settings - Which we already bypass above using DNS entry.
2. Docker Version -  This setup is successfully done on Docker version 4.18. Earlier, I have tried to install it on latest Docker version but causing SQL connection issue. I'll update this section if I get success to install on higher version but for now this is working on 4.18 version.

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.

Down the docker and clear all Docker data using the below commands. Then Run the containers again using .\up.ps1

.\down.ps1

cd docker

./clean.ps1