Skip to main content

Walkthrough: Configuring external editing hosts for XM Cloud instances

Abstract

Describes how to configure editing hosts so you can edit pages with Sitecore content and layout editors in an XM Cloud environment

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

Important

Before starting to configure editing hosts, it is important you understand what rendering and editing hosts are and how they differ.

When you create a project using the XM Cloud Deploy App, the project is set up with a default internal editing host. This editing host works out of the box on your remote XM Cloud instance. The environment variables for the internal editing host can not be changed.

Tip

If you see an error when trying to access the Experience Editor or Pages in local development and your application is based on the SXA-enabled starter 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 see errors if trying to access a page in the Experience Editor or Pages.

This walkthrough describes how to:

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 project, 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:

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

      {
        "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 root folder of the solution.

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

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:

    <?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> - random generated Sitecore API key for the rendering host.

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