Skip to main content

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

Abstract

Run an XM Cloud-compatible Sitecore XM instance and a client application locally.

When you create an XM Cloud project using the XM Cloud Deploy App and choose the starter template as the source for the initial deployment, the process also adds the starter 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.

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

To use the starter 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.

  • Rebuild search indexes.

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:

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

    If you do, you must stop it:

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

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

    If you do, you must stop it:

    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:

    nssm stop "<the name of your service>"

The starter template contains the software components and scripts to:

  • Update container images.

  • Build the containers.

  • 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.

Tip

If you are not using the Starter Kit, you might not have the init.ps1 and up.ps1 scripts in your project. You can copy them from the Starter Kit repository.

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:

    .\init.ps1 -InitEnv -LicenseXmlPath "<C:\path\to\license.xml>" -AdminPassword "<desired password>"
  5. To download the Sitecore Docker images, install and configure the containers and client application, run the following script:

    .\up.ps1
  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 deployed/copied build output.

After running the .\docker\clean.ps1 script, you must rebuild search indexes.

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 does not 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. If you are using an official Sitecore XM Cloud starter template, the repository already contains the necessary setup for enabling serialization. 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 templates created during the deployment process:

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

      {
        "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:

      {
        "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.

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:

    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.

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:

    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:

    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:

    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:

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

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:

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

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

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

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:

    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.

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:

    dotnet sitecore ser push -n "local"

When the operation is complete, you can see the new items in your locally running XM instance. 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.

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 starter 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 the 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, 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. Go to your rendering host directory (sxastarter) and start the front-end application in connected mode with the command:

    npm run start:connected
  10. 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.

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:

npm run start:connected

Rebuild search indexes