Walkthrough: Configuring external editing hosts for XM Cloud instances

The external editing host is an application you configure to support editing experiences in Pages or the Experience Editor when using a non-standard solution for creating your XM Cloud environment.

Important

Before configuring editing hosts, you must understand what rendering and editing hosts are and how they differ

When you create an environment using the XM Cloud Deploy app, the environment is set up with a default internal editing host. This editing host works out of the box on your remote XM Cloud instance. You can add environment variables to the internal editing host, but the default environment variables can't be modified, so any changes you make to them are ignored.

Tip

If you see an error when trying to access Pages or the Experience Editor in local development and your application is based on the SXA-enabled foundation template, follow the steps for configuring rendering hosts in the walkthrough for setting up your local development environment.

Setting up an external editing host is necessary if you create your XM Cloud project without using an officially supported starter kit because the default editing host configuration is not created for you. Therefore, you will see errors when accessing a page in Pages or the Experience Editor.

This walkthrough describes how to:

Update the build configuration for the XM Cloud environment

You define the build configuration for an XM Cloud environment in the xmcloud.build.json file.

To configure the editing host for the XM Cloud environment:

  1. In the root directory of your environment, open the xmcloud.build.json file. If it does not exist, create it with an empty JSON object.

  2. In the xmcloud.build.json file, for the existing JSON object, add a renderingHosts property. The property value is a key-value pair or site names and their configuration. For example:

    • For a JSS site:

      RequestResponse
      {
  "renderingHosts": {
    "<jss-site-name>": {
      "path": "./src/rendering",
      "nodeVersion": "16.3.19",
      "jssDeploymentSecret": "<secret>",
      "enabled": true,
      "type": "jss"
    }
  }
}

    • For an SXA site:

      RequestResponse
      {
  "renderingHosts": {
    "<sxa-site-name>": {
      "path": "./src/sxa-rendering",
      "nodeVersion": "16.3.19",
      "jssDeploymentSecret": "<secret>",
      "enabled": true,
      "type": "sxa"
    }
  }
}

    Modify the example as follows:

    • Replace <jss-site-name> or <sxa-site-name> with the unique name of your site, as defined in the application's package.json file.

    • Replace the path value with the path to the source code of the SXA/JSS application in your solution relative to the solution's root folder.

    • Replace the nodeVersion with the specific Node.js version for the application.

    • Replace the jssDeploymentSecret<secret> value with a randomly generated string of 32 or more characters. The deployment secret is a shared secret that authorizes the application to deploy items to the Sitecore instance. It populates the value for deploySecret in the scjssconfig.json file.

    • Set the enabled value to true to enable the site. The default value is false.

    • Set the type value to sxa or jss. The default value is jss.

      Note

      An SXA site is created from an SXA template and uses item-based configuration. A JSS site is created from a JSS template and uses file-based configuration.

Configure the Content Management (CM) instance

To enable the editing host, you must modify the instance configuration using a configuration patch.

To modify the configuration:

  • Create a configuration patch file where you configure sites and apps. For example:

    RequestResponse
    <?xml version="1.0"?>

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"
               xmlns:set="http://www.sitecore.net/xmlconfig/set/">
  <sitecore>
    <sites>
      <!--
        JSS Site Registration
        This configures the site with Sitecore - i.e. host headers, item paths.
        If your JSS app lives within an existing Sitecore site, this may not be necessary.
      -->
      <site name="xmcloud"
            inherits="website"
            hostName="$(env:host)"
            rootPath="/sitecore/content/xmcloud"
            patch:before="site[@name='website']" />
    </sites>
    <javaScriptServices>
      <apps>
        <!--
          JSS App Registration
          The JSS app needs to be registered in order to support layout service and import services.

          There are many available attributes, and they inherit the defaults if not explicitly specified here.
          Defaults are defined in `/App_Config/Sitecore/JavaScriptServices/Sitecore.JavaScriptServices.Apps.config`

          NOTE: graphQLEndpoint enables _Integrated GraphQL_. If not using integrated GraphQL, it can be removed.

          NOTE: This app configuration assumes a Sitecore-first approach and thus disables the JSS Workflow for
          initial app import, and does not protect imported items.
        -->
        <app name="xmcloud"
             sitecorePath="/sitecore/content/xmcloud"
             graphQLEndpoint="/sitecore/api/graph/edge"
             serverSideRenderingEngine="http"
             serverSideRenderingEngineEndpointUrl="$(env:RENDERING_HOST_INTERNAL_URI_<rendering-host-name>)/api/editing/render"
             serverSideRenderingEngineApplicationUrl="http://$(env:SITECORE_EDITING_HOST_PUBLIC_HOST_<rendering-host-name>)"
             useLanguageSpecificLayout="true"
             defaultWorkflow=""
             protectDeveloperItems="false"
             deploymentSecret="$(env:JSS_DEPLOYMENT_SECRET_<rendering-host-name>)"
             debugSecurity="false"
             inherits="defaults" />
      </apps>    
    </javaScriptServices>
  </sitecore>
</configuration>
Tip

For additional attributes that you can use to configure apps in the Sitecore configuration patch, see the documentation for App Configuration API.

When configuring sites and apps in the configuration patch file, you can use the following environment variables:

  • host - internal hostname.

  • RENDERING_HOST_INTERNAL_URI_<rendering-host-name> - internal URI to rendering host. For example, http://internal-rendering-name.

  • SITECORE_EDITING_HOST_PUBLIC_HOST_<rendering-host-name> - public rendering host URI. For example, public-rendering-host.

  • JSS_DEPLOYMENT_SECRET_<rendering-host-name> - the same value as jssDeploymentSecret in the xmcloud.build.json. Replace <rendering-host-name> with the site name value you provided in the xmcloud.build.json file.

  • SITECORE_JSS_EDITING_SECRET - random generated secret. It must have the same value as JSS_EDITING_SECRET for the rendering host.

  • SITECORE_API_KEY_<rendering-host-name> - a randomly generated Sitecore API key for the rendering host.

Configure the front-end application

To configure the editing host runtime:

  • Use the following variables:

    • PUBLIC_URL - public URL. For example, https://public-rendering-host.

    • SITECORE_API_KEY - a randomly generated Sitecore API key for a particular rendering host.

    • JSS_EDITING_SECRET - a randomly generated secret value. The same value as SITECORE_JSS_EDITING_SECRET in the CM configuration patch.

    • SITECORE_API_HOST - internal URL http://internal-cm-name.

    • NEXTJS_DIST_DIR - .next-container.

During deployment, XM Cloud creates the scjssconfig.json file. The file is generated automatically during the first deployment of your XM Cloud solution based on the integration configuration.

Do you have some feedback for us?

If you have suggestions for improving this article,