Sitecore Horizon 9.3 – installation guide

What is Sitecore Horizon?

Sitecore Horizon 9.3 (referred as Horizon for brevity in this blog) is the new alternative approach to editing content that is now available together with release of Sitecore Experience Platform 9.3 since late November 2019. Horizon is a separate Module that can be installed and is hosted separately from the main Sitecore XP 9.3 instance.

Sitecore previously announced Horizon in Symposium 2017 with a preview version released with Sitecore XP 9.1

The new editing environment in Sitecore XP 9.3, known as “Horizon” offers brands an easy to use, intuitive, and contextual interface with everything a user needs for easy navigation. The new editor user interface sets a foundation for the future and also provides real-time contextual insights as content is created and published, giving marketers the knowledge they need to drive improved conversions
~~~~
Sitecore official Symposium 2019 announcement

Horizon architecture at a glance

• Horizon introduces a new IIS website instance, the content Authoring host application
• Horizon deploys an integration module to every CM  instance
• Horizon client application is built with Angular 7.2 utilizing Node.js for server-side rendering
• Horizon client application uses GraphQL-based backend API to communicate with backend. This is similar to Sitecore JSS services
• HTTPs requirement for communications between CM instance and the Authoring host application
• User authentication via the Sitecore Identity Service

Horizon Installation – Prerequisites

• Installation assets and guide available from dev.sitecore.net on the Sitecore Horizon 9.3.0 page
• As prerequisite you must install Sitecore Experience Platform 9.3 or later. Also verify that
  • Sitecore CM instance has HTTPS enabled
  • Sitecore Identity must be installed
  • WebSocket Protocol is enabled in Windows Server Manager. Please see the screenshot below, where you need to tick to enable this feature and update your system.

• The following tooling must be installed
  • Sitecore Install Framework 2.2.0 or later
  • .NET Core runtime and hosting bundle 2.1
  • Node v10.16.0 and npm 6

Horizon Installation – step by step guide

1. This is based on an existing XP0 Developer Workstation Sitecore XP 9.3 installation. Please follow my blog post for a guide on how to setup Sitecore XP 9.3 on your on-premises developer instance.
2. Unpack the Sitecore Horizon 9.3.0.zip package to a working folder (as shown in screenshot below). You will then need to update the parameter.ps1 PowerShell script with parameters for the following:
   • ContentManagementInstanceName – specify CM instance name
   • ContentManagementWebProtocol – this must be HTTPS
   • SitecoreIdentityServerPhysicalPath – specify path to Identity Server
   • SitecoreIdentityServerPoolName – specify Identify Server application pool name
   • SitecoreIdentityServerSiteName – specify Identity Server site name
   • LicensePath – specify your license full path (including file name)
   • AuthoringHostName – (recommended authoringhost.cmdomain.com as sub-domain of CM instance)
3. After you save your changes to parameter.ps1 PowerShell script, simply run the install.ps1 PowerShell script from your command prompt or PowerShell command to install Horizon

Horizon install package extracted showing parameters.ps1 script

Below is a sample parameters.ps1 script with the parameters specified. Notice the license path must include the file name.

Sample parameters.ps1 script with values

Whilst Horizon is installing, you will see the progress screen similar to the one shown below

Horizon installation in progress

Launching Sitecore Horizon

Sitecore Horizon 9.3 once successfully installed can be launched from the Launchpad of your main Sitecore XP 9.3 as shown below

Click on Horizon “missile” icon to launch the Horizon Authoring host application, as shown below

Congratulations! You have successfully installed Horizon when you see the above page. You will notice that Horizon is opened on a separate tab from your main Sitecore instance Launchpad

What changes does Horizon introduce to wwwroot

As mentioned above in the architecture at a glance, Horizon create a new IIS website as well as integration module to every CM instance.

Below is a screenshot showing IIS websites before and after Horizon is installed.

IIS Websites before horizon

And below are the changes to your main Sitecore instance (wwwroot changes).

Red highlight indicates the file(s) were modified. Blue/Purple indicates new files were introduced

wwwroot changes introduced by Horizon to CM instance

And below are the changes to your Sitecore Identity server (wwwroot changes).

Red highlight indicate the file(s) were modified.

Troubleshooting Installation Issues

You may come across installation issues. Below is how you can troubleshoot them

Node.js issues

You may come across Node.js issues which means Horizon will not load successfully when launched. You may get the error message below on your browser after launching Horizon

Failed to render a page: InternalServerError when launching Horizon, see screenshot below 

You may get exceptions reported in the logs similar to this one below

An unhandled exception was thrown by the application.
System.InvalidOperationException: Failed to start Node process. To resolve this:.
[1] Ensure that Node.js is installed and can be found in one of the PATH directories.
    Current PATH enviroment variable is:
    Make sure the Node executable is in one of those directories, or update your PATH.

To resolve the Node.js issue, try the following options:

A) If you are using Node.js version management utility (NVM) to manage your NodeJS versions, ensure you have given the IIS application pool permissions to your NVM Roaming folder. Below is a screenshot showing how to give permissions

setting permission on nvm roaming folder

B) If you are not using NVM, then please try uninstall Node.js and then re-install it again using the Windows Installer. Please refer to the Sitecore Horizon 9.3 Installation guide on the required Node.js version

Enabling logging on Authoring.Host.dll

Horizon logs are written on the logs sub-folder located at the wwwroot of the Horizon instance, as shown below:

update web.config to enable logs

If you can’t see any log files in the logs sub-folder, you can update the web.config file located at the wwwroot of the Horizon instance as shown below. Simply set the stdoutLogEnabled =”true” save your changes, and then recycle the Horizon app pool

Hope you find this post useful. Please watch this space as I will blog more about Horizon, including a deep dive on its features among other areas.