Install Headless Services using the package .zip file

Version: 21.x

The procedure for installing the Headless Services module using a package .zip file depends on your Sitecore environment:

  • On a standalone Sitecore instance or, in a scaled environment, on the CM instance, you must install Sitecore Headless Services.

  • For scaled Sitecore installations (production environments with separate CM and CD servers), you must configure the CD instance in a scaled Sitecore environment.

Install Sitecore Headless Services

On a Standalone Sitecore instance or, in a scaled environment, on the CM instance, you must install Sitecore Headless Services only once in a Sitecore headless environment.

To install Sitecore Headless Services:

  1. Download the Sitecore Headless Services package compatible with your Sitecore version. See the Sitecore modules compatibility table for Sitecore XP.

  2. Log in to your Sitecore instance.

  3. Open the Desktop. On the Sitecore menu (lower left), click Development Tools, then Installation Wizard.

  4. Follow the wizard to install the Sitecore Headless Services zip package.

  5. For Sitecore 9.0.x only (not 9.1), in your /Web.config file, alter the binding redirect for Newtonsoft.Json:

    RequestResponse
    <dependentAssembly>
  <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" />
  <!-- change the oldVersion from 9.0.0.0 to 11.0.0.0. Leave newVersion alone (do not make it 11.0). -->
  <bindingRedirect oldVersion="0.0.0.0-11.0.0.0" newVersion="9.0.0.0" />
</dependentAssembly>

  6. To verify your server components installation worked, visit http://your-sitecore-instance/sitecore/api/layout/render/jss?item=/&sc_apikey=TEST. You receive the message HTTP Error 400.0 - API key is not valid if it is working correctly.

    Tip

    Browsers might obscure the message behind a custom error page for HTTP 400. You might need tools like Postman or browser-specific developer tools to see this message.

Configure the CD instance in a scaled Sitecore environment

If you are installing Sitecore Headless Services to a scaled Sitecore environment (production environments with separate CM and CD servers), you must configure the CD instance.

To configure the CD instance to install the Headless Services module:

  1. Extract the server components Sitecore package.

  2. Extract the inner package.zip file. Ignore any unzip warnings about sc_*.txt files.

  3. Deploy the following package/files files in the files folder to your CD server's webroot: App_Config, bin, sitecore, Views, sitecore modules\items\web and sitecore modules\items\core.

  4. On a CD server, in /Web.config , in the <handlers> section, add the following key:

    RequestResponse
    <add verb="*" path="sitecorejss_media.ashx" type="Sitecore.JavaScriptServices.Media.MediaRequestHandler, Sitecore.JavaScriptServices.Media" name="Sitecore.JavaScriptServices.Media.MediaRequestHandler" />

Do you have some feedback for us?

If you have suggestions for improving this article,