Walkthrough: Setting up your full-stack XM Cloud local development environment

When you create an XM Cloud project using the XM Cloud Deploy app and choose the foundation template as the source for the initial deployment, the process also adds the foundation template to the source control repository you configured for the initial environment.

You can use the resulting codebase to set up your local development environment based on Docker containers.

Note

Make sure you are using Docker v.2, as explained here.

The following video shows you how to set up your environment:

To use the foundation template, you must have the following software components on your workstation:

This walkthrough describes how to:

  • Prepare the environment.

  • Configure and run the solution.

  • Configure item serialization.

  • Authorize with the XM Cloud organization.

  • Connect an XM Cloud environment.

  • Connect the local environment.

  • Pull serialized items from XM Cloud to your local repository.

  • Push serialized items into the local environment.

  • Configure the editing host for your local environment.

Prepare the environment

Before starting the containers, you must ensure the necessary ports are accessible.

To prepare the environment for running the solution:

  1. Open PowerShell with administrator privileges.

  2. Check if you have the Internet Information Server running on port 443:

    RequestResponseshell
    Get-Process -Id (Get-NetTCPConnection -LocalPort 443).OwningProcess

    If you do, you must stop it:

    RequestResponseshell
    iisreset /stop
  3. Check if you have Apache Solr or any other service running on port 8984:

    RequestResponseshell
    Get-Process -Id (Get-NetTCPConnection -LocalPort 8984).OwningProcess

    If you do, you must stop it:

    RequestResponseshell
    Stop-Service -Name "<the name of your service>"

    Alternatively, if you have started it with Non-Sucking Service Manager, stop it with the following command:

    RequestResponseshell
    nssm stop "<the name of your service>"

Configure and run the solution

The foundation template contains the software components and scripts to:

  • Update container images.

  • Build the containers.

  • Set up the necessary hosts.

  • Start the containers.

  • Start the Sitecore XM Content Management (CM) instance.

  • Install the Sitecore CLI and the necessary plugins.

  • Populate the Solr Managed Schemas.

  • Rebuild indexes.

  • Serialize and push developer-managed items to the Sitecore XM instance.

  • Open the CM instance and client app in the browser.

Important

Even if you plan on running multiple content management instances (multiple projects) locally, the hostname of every instance must follow the *.xmcloudcm.localhost pattern for authentication to work correctly. In other words, you can have hostnames such as myproject.xmcloudcm.localhost but not cm.mycompany.localhost.

To set up the template for running locally and start the containers:

  1. Open PowerShell with administrator privileges.

  2. In your projects directory, clone the repository you configured for the XM Cloud project.

  3. Using a command-line interface, go to the root of your repository folder.

  4. To prepare the Sitecore container environment, run the script init.ps1 from the root directory of the project:

    RequestResponseshell
    .\init.ps1 -InitEnv -LicenseXmlPath "<C:\path\to\license.xml>" -AdminPassword "<desired password>"
    Tip

    If you are not using the foundation template, you might not have the init.ps1 script in your project. You can copy the init.ps1 script from the foundation template repository.

  5. To download the Sitecore Docker images, install and configure the containers and client application, run the following script:

    RequestResponseshell
    .\up.ps1
    Tip

    If you are not using the foundation template, you might not have the up.ps1 script in your project. You can copy the up.ps1 script from the foundation template repository.

  6. When prompted, in your browser, log in to the Sitecore XM instance and accept the device authorization.

  7. If you are a member of multiple organizations, select the organization for the current project.

  8. Wait for the startup script to open browser tabs for the rendered site and the Sitecore Launchpad.

Important

If you have to reset the state of your containers, you can run the \docker\clean.ps1 script. It clears all mounted data and the deployed/copied build output. After running the .\docker\clean.ps1 script, you must rebuild search indexes.

Configure item serialization

When the local XM Cloud instance is running, if you inspect the content tree using the Content Editor tool, you can see that the local instance of XM Cloud doesn't have any of the items for your new site. When you set up your project, the new site was only created in your remote XM Cloud instance.

You must, therefore, transfer the site items to your local and remote repositories so that every developer has them available.

You can synchronize items between environments with Sitecore Serialization. The repository already contains the necessary setup for enabling serialization if you are using an official Sitecore XM Cloud foundation template. It also includes the src/renderinghost.module.json file that configures the rendering host item serialization. While developing locally, however, you need additional configuration.

To create a new serialization configuration:

  1. In the src folder, create a new serialization module file. Give it a suggestive name, for example, mysite.module.json.

  2. Replace the namespace value with a unique value, such as the site name. For example, MySite.

  3. Copy the content from the existing serialization module definition as a starting point, and modify the items property to include:

    • The placeholder settings:

      RequestResponsejson
      {
        "name": "layout",
        "path": "/sitecore/layout/Placeholder Settings/Project/placeholdersite",
        "allowedPushOperations": "CreateUpdateAndDelete"
      }
    • The templates created during the deployment process:

      RequestResponsejson
      {
        "name": "templates",
        "path": "/sitecore/Templates/Project/MySite",
        "allowedPushOperations": "CreateUpdateAndDelete"
      }
    • The content item, which includes tenants and sites:

      RequestResponsejson
      {
        "name": "contentRoot",
        "path": "/sitecore/content",
        "allowedPushOperations": "CreateUpdateAndDelete"
      }
      Caution

      This configuration serializes the entire content tree because it does not have a single-item scope. When content authors start working on items, you must change this configuration to prevent overwriting their work when performing serialization push operations.

    • The media items:

      RequestResponsejson
      {
        "name": "media",
        "path": "/sitecore/Media Library/Project/MySite",
        "allowedPushOperations": "CreateUpdateAndDelete"
      }

    You can configure additional paths such as renderings, layouts, settings, and more after they are created in the XM Cloud instance.

  4. Save the file.

Authorize within the XM Cloud organization

Before performing operations against a remote XM Cloud instance, you must authenticate within your XM Cloud organization.

To authorize the local project in your XM Cloud organization:

  • Run the following command:

    RequestResponseshell
    dotnet sitecore cloud login

    Follow the steps in the user interface to log in and authorize your device. When you finalize the authentication process, the connectivity information is stored in the .sitecore/user.json file.

Connect an XM Cloud environment

You can connect to one or more remote environments.

To connect to an XM Cloud environment:

  1. Obtain the ID of your XM Cloud project by running the command:

    RequestResponseshell
    dotnet sitecore cloud project list

    Identify the XM Cloud project you are working on and copy the ID.

  2. Obtain the ID of your XM Cloud environment by running the command:

    RequestResponseshell
    dotnet sitecore cloud environment list --project-id <project-id>

    Identify the environment you want to connect to and copy the ID.

  3. Run the XM Cloud environment connect command:

    RequestResponseshell
    dotnet sitecore cloud environment connect -id <environment-id> --allow-write true

The process updates the .sitecore/user.json file with the environment connection configuration if the connection is successful. Assuming you named your XM Cloud environment dev , the .sitecore/user.json file now contains a dev key in the endpoints object:

RequestResponsejson
{
  "endpoints": {
    "xmCloud": {
      ...
    },
    "dev": {
        "ref": "XMCloud",
        "allowWrite": true,
        "host": "<the environment host>",
        "variables": {}
    }
  }
}

Connect the local environment

You connect the local environment with the Sitecore CLI connect command.

To connect:

  • In a terminal, go to the root directory of the local project and run the following command:

    RequestResponseshell
    dotnet sitecore connect --ref xmcloud --cm https://xmcloudcm.localhost --allow-write true -n local

The process updates the .sitecore/user.json file with the local environment connection configuration:

RequestResponsejson
{
  "endpoints": {
    "xmCloud": {
      ...
    },
    "dev": {
      ...
    },
    "local": {
        "ref": "xmcloudlocal",
        "allowWrite": true,
        "host": "https://xmcloudcm.localhost",
        "variables": {}
    }
  }
}

Pull serialized items from XM Cloud to your local repository

With authentication/authorization in place and the necessary environment references added to .sitecore/user.json, your local project is ready to perform serialization operations.

To pull serialized items from the remote XM Cloud environment:

  • In the terminal, run the Sitecore serialization pull command, specifying the environment name as configured in the .sitecore/user.json file:

    RequestResponseshell
    dotnet sitecore ser pull -n "dev"

    The command output shows what items have been serialized.

Based on your serialization configuration, the source code now contains the src/items folder with the subfolders content-root, media, and templates.

Push serialized items into the local environment

Now that you have the serialized items created in your remote XM Cloud environment in your local repository, you can push them into your local XM instance.

To push the serialized items into your locally running XM instance:

  • In the terminal, run the Sitecore serialization push command, specifying the local environment name as configured in the .sitecore/user.json file:

    RequestResponseshell
    dotnet sitecore ser push -n "local"

You can see the new items in your locally running XM instance when the operation is complete. You can now commit and push the serialized items to your remote version control repository.

Note

The command serialization push (ser push) does not publish items. You must manually publish them.

Configure the editing host for your local environment

If you try to open an item in the Experience Editor at this time, you get an error message because the rendering host application is not set up for local development. Because the solution is based on Sitecore Experience Accelerator (SXA), you can configure the rendering host using items.

To configure the rendering host:

  1. In the content tree, under your new site, in the Settings item, in the App Settings section, verify that the App Name field contains the name of your application. This name must match the config.appName setting in the src/<app-folder>/package.json file of the front-end app.

    Tip

    If you used the SXA-enabled foundation template, the <app-folder> is sxastarter.

  2. In your site's tree of items, in the /content/<SiteName>/<AppName>/Settings/Site Grouping/<your-site> item, in the Settings section, in the Predefined application rendering host field, verify that the field references the default rendering host.

  3. In the /System/Settings/Services/Rendering Hosts/Default item that contains the default rendering host definition, in the Data section, in the Application name field, verify that the application name is correct. If not, change it to match the config.appName setting in the package.json file of your rendering app.

    Tip

    You can also leave the field blank. That way, the field uses, by default, the value you configured in step 1.

  4. Right-click the /System/Settings/Services/Rendering Hosts/ item and click Insert then Rendering host.

  5. In the Message dialog, enter the name of your configuration. For example, Local.

  6. Open the /System/Settings/Services/Rendering Hosts/Local configuration in the Data section, and fill in the fields as follows:

    • In the Server side rendering engine endpoint URL field, enter the URL to the front-end app's API route for rendering in editing mode. For example, http://rendering:3000/api/editing/render.

      Tip

      You can derive the value for this field from the RENDERING_HOST_INTERNAL_URI environment variable defined in the docker-compose.override.yml file in the root of your project, usually http://rendering:3000, and the Next.js API route for rendering the app in editing mode (always /api/editing/render).

    • In the Server side rendering engine application URL field, enter the value of the RENDERING_HOST_INTERNAL_URI environment variable.

    • In the Application name field, enter the name of your front-end application as configured in the package.json file.

  7. Save the item.

  8. In your site's tree of items, in the /content/<sitename>/<appname>/Settings/Site Grouping/<appname> item, in the Settings section, the Predefined application rendering host field, select the Local rendering host definition and save the item.

    Important

    This item must not be overwritten in your remote instances.

  9. Run the following CLI command to create a scjssconfig.json file with the ID of the API key item (the item ID for /sitecore/system/Settings/Services/API Keys/xmcloudpreview), and the Sitecore hostname (https://xmcloudcm.localhost) in the default installation location:

    RequestResponseshell
    jss setup
  10. Go to your rendering host directory (sxastarter) and start the front-end application in connected mode with the command:

    RequestResponseshell
    npm run start:connected
  11. To verify your setup, open a content item in the Experience Editor. If your rendering host is running and your setup is correct, your rendering host must be running in connected mode.

Note

Instead of creating a new rendering host definition, you can modify the default definition field values in your local environment. If you do so, you must ensure that you do not overwrite the default configuration in your remote instance.

Next steps

With this setup complete, you can start developing your XM Cloud solution and your front-end application.

As you work, you can use the Sitecore CLI to perform common development tasks such as:

For front-end development, start the front-end application in connected mode by navigating to your rendering host directory (sxastarter) and running the command:

RequestResponseshell
npm run start:connected

Do you have some feedback for us?

If you have suggestions for improving this article,