Installing Sitecore 9.3 And Horizon

TLDR

Installing Sitecore Horizon involves first installing Sitecore 9.3 and then Installing Horizon as a separate module from here. Follow the Sitecore Horizon install instructions below.

Sitecore 9.3 dropped yesterday and It ships with a number of updates to JSS, SXA, Sitecore MVC and Sitecore Forms and more. However the Mostly Highly anticipated part of this release is Horizon – Sitecore’s all new Page Editing interface (yes ‘Page Editor’ is back – but this time built with Node and much faster). Horizon also has Simulator Mode and Insights View which look pretty cool.

For those of you keen to take a look at Horizon in more detail this blog post is going to give you an overview of how to install Sitecore 9.3 and Install Sitecore Horizon on a local development environment.

Sitecore 9.3 Install

In 9.2 Sitecore released a new simple installer called SIA (Sitecore Installer Assistant) and that is what we are going to use to install Sitecore 9.3. You can also install Sitecore via SIF and ARM Templates but were going for the quickest and simplest option in this post.

SIA will also install all of the elements now required to run an Sitecore instance for you such as Solr, Identity Server and xConnect. It doesn’t however install Horizon for you so we’l also cover that later on in this post.

Step 1 – Download The Installer

You want the ‘Graphical setup package for XP Single’ package from this page:
https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/93/Sitecore_Experience_Platform_93_Initial_Release.aspx.

Download the zip file, unblock it and extract it.

Step 2 – SIA Pre-Requisites

To use SIA (or install Sitecore 9.3 in any way) you will need to have the following in place:

IIS 10
.NET Framework 4.7.2
.NET Core 2.1.12 Windows Hosting Module
SQL Server 2016 SP2 and 2017
Microsoft PowerShell® version 5.1 or later
An Valid Sitecore Licence for 9.3

Step 3 – SIA Install Process

Run the Setup.exe file from the extracted folder and click ‘Start’.

There are a number of great blog posts out there that cover using SIA in detail – such as Robbert Hocks excellent guide, so I’m not going to go through all the installer steps in detail, However I will summarise them here and provide some tips.

Pre-requisites – SIA uses SIF under the hood and requires version 2.2 of SIF.
It will try and install it for you but If you have issues with the installer failing at this step you may wish to check which version(s) of SIF you currently have installed:

Get-InstalledModule -Name SitecoreInstallFramework -AllVersions

You might need to uninstall old versions before trying SIA again. More info on this here: https://www.koenheye.be/multiple-versions-of-the-sitecore-install-framework/
Install Solr – Solr is now required as part of the install. If you already have an instance of Solr running on port 8983 then choose a different port for your 9.3 install. I would suggest something like ‘sc93-‘ as the prefix as SIA installs Solr 8.1.1 for you and when it creates the windows service and folder it appends ‘solr-8.1.1’ to the prefix you enter like so: ‘sc93-solr-8.1.1’.
–
Sitecore Settings – SIA will append ‘sc.dev.local’ to whatever you add as the instance prefix so ’93’ would make sense here. It will also use this prefix to name the XConnect and Identity Server sites too:

I bet most people will still us ‘admin/b’ as the username and password too :-).

Once you’ve completed the other steps in the installer it will validate the install and should complete the installation in around 10-15 minutes. If you have any issues then check the logs in SIA. If all went well you should be able to open your site by clicking the button on the final SIA screen or going to it in your browser, e.g: https://93sc.dev.local/.

Sitecore Horizon Install

You may have noticed during the install that SXA was an optional module you could install from SIA, unfortunately Horizon isn’t, hopefully it will be in future releases. Therefore we need to install Horizon separately. I hit a few stumbling blocks with the install which I’ll cover at the end.

Step 1 – Download The Install Files

You want the ‘Sitecore Horizon for On Premises deployment’ package from this page: https://dev.sitecore.net/Downloads/Sitecore_Horizon/93/Sitecore_Horizon_93_Initial_version.aspx

Download the zip file, unblock it and extract it.

Step 2 – Sitecore Horizon Install Pre-Requisites

Before you begin the install ensure you have the following in place:

You’ve installed Sitecore with HTTPS, SIF 2.2.0 & Sitecore Identity is installed (you will have done if you’ve used SIA ‘as is’)
Web socket protocol is installed, you can enable this under ‘turn windows features on and off’.

More info here: https://docs.microsoft.com/en-us/iis/get-started/whats-new-in-iis-8/iis-80-websocket-protocol-support

You have the correct version of the ASP.NET Core/.NET Core: Runtime & Hosting Bundle 2.1. You can check the version you have by running:

dotnet --info

dot-net-runtime

You have Node 10 and npm 6 installed. If you don’t have Node installed at all then use this download package for Windows: https://nodejs.org/dist/v10.0.0/node-v10.0.0-x86.msi.
I prefer to use NVM myself to install and manage node versions but I could not get Horizon to start for some reason despite having node registered correctly on my Path variable in Windows.
Your Sitecore licence must also include Horizon or you won’t be able to run it.

Step 3 – Sitecore Horizon Install Process

Open up the parameters.ps1 file from the extracted folder and set values for the following parameters:

$ContentManagementInstanceName – this should be the name of the Sitecore instance you just created in IIS via SIA – e.g “93sc.dev.local”.

$ContentManagementWebProtocol – this should always be “https”

$SitecoreIdentityServerPhysicalPath – this should be the path to the Sitecore Identify instance you just created in IIS via SIA – e.g: “C:\inetpub\wwwroot\93identityserver.dev.local”

$SitecoreIdentityServerPoolName – this should be the name of the Sitecore Identify instance app pool – e.g: “93identityserver.dev.local”

$SitecoreIdentityServerSiteName – this should be the name of the Sitecore Identify instance – e.g: “93identityserver.dev.local”

$LicensePath – this should be the path to where your licence file can be found – e.g: “C:\inetpub\wwwroot\93sc.dev.local\App_Data\license.xml” – This one is important to get right to avoid some of the errors I hit with the license ending up in the wrong folder (see Troubleshooting section), the official installation PDF isn’t clear about this but it is the FULL PATH including the FILENAME.

$authoringHostName – this will be the url that Horizon will run on, the install file tries to set this for you based on the name of your Sitecore instance etc but you can set this if you wish, I set this to: “horizon.93sc.dev.local”. – Others have mentioned to me that when they didn’t set this they had issues. Also make sure you name the Host Name using the same domain as the Sitecore Content Management instance, so that the format is like so: {something}.{cmsinstancename} as above. as in the official install PDF Guide it mentions a change regarding how cookies work in Chrome which will break this if you don’t follow this format.

Now open up the Install.ps1 file and run it (make sure you are running it as an Administrator).

horizon-install1

Wait a few minutes and the install process should complete:

Once it has completed you can either go to your horizon instance in your browser, e.g “horizon.93sc.dev.local” or you can re-start and open up your Sitecore 9.3 instance and click on the swanky new Horizon Icon that you should see on your Launchpad:

All being well Horizon should load and you should see the following screen:

horrizon-complete

Sitecore Horizon Install Troubleshooting

One of the main reasons I wrote this guide is I had a few issues with the install. I’m going to outline them below and the fixes required.

Debugging Horizon

First some tips on Debugging Horizon as I couldn’t find much out there on this.

Run the Authoring.Host.dll directly from the root folder (e.g: C:\inetpub\wwwroot\horizon.93sc.dev.local) like so to give you direct output on the errors in the console:

dotnet Authoring.Host.dll

run-host

Check the logs in your Horizon app (e.g: C:\inetpub\wwwroot\horizon.93sc.dev.local). By default I think they just write to the root folder. You will see two different logs: ‘AuthoringHost’ and ‘stdout’ logs. If you are not seeing any logs then edit the web.config file at the root of the Horizon app and check stdoutLogEnabled is true, you can also change the path for the log files here.

stdoutLogEnabled=”true” stdoutLogFile=”C:\inetpub\wwwroot\horizon.93sc.dev.local\logs\stdout” />

Errors & Issues

Here are some issues I had which I had to resolve.

HTTP Error 502 – Process Failure

This error basically just means that dotnet core could not run the app. It’s a pretty generic error message which can mean a number of things so you need to dig into the logs to find out more info.

horizon-error

I didn’t have an issue with my .net versions but one key thing to check first is that you have the right versions of the .net core runtime installed.

Licence Error

Looking in the logs for more info this is the first error I was getting:

Unhandled Exception: System.InvalidOperationException: License file doesn’t exist on disk.
at Sitecore.Framework.Runtime.Commands.SitecoreHostCommand.LoadLicenseXml(String filePath, String contentRootPath)
at Sitecore.Framework.Runtime.Commands.SitecoreHostCommand.OnExecuteAsync(CommandLineApplication app)
at McMaster.Extensions.CommandLineUtils.Conventions.ExecuteMethodConvention.InvokeAsync(MethodInfo method, Object instance, Object[] arguments) in C:\projects\commandlineutils\src\CommandLineUtils\Conventions\ExecuteMethodConvention.cs:line 77

To resolve this I needed to copy the licence folder into the /sitecoreruntime folder e.g: c:\inetpub\wwwroot\horizonsc93sc.dev.local\sitecoreruntime.
I’m not sure if this is a bug but the installer seemed to put the licence file in the wrong location (/config).
Thanks to Vlad for his help with this: https://sitecore.stackexchange.com/questions/23209/running-horizon-failed-http-error-502-5-process-failure.

Patch File Error

This was the 2nd error I was seeing:

Unhandled Exception: Sitecore.Framework.Configuration.Patcher.ConfigurationException: An error occurred during applying the patch file: C:\inetpub\wwwroot\horizon.93sc.dev.local\Config\license.xml —> System.Exception: Could not merge node ‘signedlicense’ in patch file ‘license.xml’
at Sitecore.Framework.Configuration.Patcher.XmlPatcher.ShouldPatchNode(XmlNode target, IXmlElement patch)
at Sitecore.Framework.Configuration.Patcher.XmlPatcher.Merge(XmlNode target, IXmlElement patch)
at Sitecore.Framework.Configuration.Patcher.XmlPatcher.ApplyPatch(String filename, XmlNode node)
at Sitecore.Framework.Configuration.Patcher.ConfigReader.LoadIncludeFiles(IEnumerable`1 files, XmlNode node)

To resolve this error I had to remove the licence that was not needed from /config (e.g: C:\inetpub\wwwroot\horizon.93sc.dev.local\Config ) as this was confusing Horizon.

Failed to render a page

I was seeing this error. This means that Horizon is running now but there is an failure in rendering the application.

NodeJs Error

Looking in the logs for more info this is the 3rd error I was seeing:

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: C:\Program Files (x86)\Common Files\Oracle\Java\javapath;C:\Program Files (x86)\Gpg4win\..\GnuPG\bin;C:\Program Files\azcopy;C:\Program Files\Git\cmd;C:\Program Files (x86)\dotnet\;C:\Users\Adam Seabridge\AppData\Roaming\nvm;C:\Program Files\nodejs;…
Make sure the Node executable is in one of those directories, or update your PATH.

I had this issue for two reasons:

1) I was trying to use NVM to manage my node versions and it would not find my node version even though node was registered correctly on my path. I couldn’t resolve this so ended up installing Node using the Windows installer instead of NVM.
2) I needed to restart IIS after I’d installed node. I would recommend a reboot of your machine after you install Node.

That all folks. Hopefully others who are keen to see Horizon in action will find this useful.
Feel free to comment or tweet me with any suggestions on any of the installation process or things I’ve missed.

You can find the docs on Horizon here. Enjoy.

The Business Case & Considerations for a Sitecore 9.2 Upgrade

I don’t often write Sitecore blog posts from a business perspective but I today I thought I would as I think some Sitecore customers are still on 8.x or 9.0 and are considering an upgrade to Sitecore 9.2.

With Sitecore 9.3 likely to be released later this year and mainstream support for 8.2 and below running out in December now is a good time to consider upgrading.

In this post I’m going to outline what the benefits of moving to 9.2 are and also the considerations you should make before embarking on an upgrade.

What are Benefits / Features of Sitecore 9.2?

This is usually one of the first questions that will be asked. I’m not going to keep this fairly high-level as there are many in-depth blog posts out there on Sitecore 9.1 & 9.2 features but the following should provide a succinct summary.

Sitecore 9.1 & 9.2 bring a lot of new features and there has been a big focus on splitting features and functionality out from the previous large monolithic architecture to a smaller modern micro-service based architecture:

Sitecore Cortex – Sitecore’s new Machine Learning Brain which can Suggested Personalisation and process and leverage customer data
Sitecore Identity – Single Sign On and Federated Authentication (using IdentityServer)
Sitecore Universal Tracker – Provides an central Analytics API to track interactions from any device (e.g mobile apps, IoT, AR and VR)
Sitecore JavaScript Services (JSS) – allows development of apps using front-end frameworks such as Angular, React and Vue, using Sitecore as the source for the data (including SXA & Sitecore Forms support in 9.2).
Sitecore Accelerator Framework (SXA) Accessibility Improvements – SXA has been around for a couple of years and is a package or pre-built components for Sitecore allowing you to get sites up and running quicker.
Sitecore Host – A lean common runtime for .NET Core applications (Powers: Horizon, Universal Tracker, Sitecore Identity)
Helix Configuration – 9.1 shipped with some Helix configuration already setup. Helix is Sitecore’s recommended approach to building Sitecore Sites it sets out an number of overall design principles and conventions to follow.
Sitecore Installer Assistant (SIA) – 9.2 provides a new GUI for easily installing Sitecore in a few clicks
SSL offloading – 9.2 provides an SSL offloading config to Improve security and performance by shifting SSL Processing onto separate processors
Active Personalization Dashboard – 9.2 has a new new dashboard which provides an overview of all personalization actively occurring, providing visibility of poorly/well performing tactics to act upon.
Many other improvements including: Search, Content Delivery, xDB and Analytics, Sitecore Forms, EXM, SIF(2), YAML Item Serialization, Bug Fixes and performance Improvements

But We’re on Sitecore 8.2 or below, what else do I get?

Mainstream Support

If you are yet to upgrade to Sitecore 9 then you need to consider this soon as Mainstream support for 8.2 and below expires in December 2019. https://kb.sitecore.net/articles/641167
This means that whilst Sitecore will still provide security updates and fixes and endeavour to assist with product incidents they may not provide support for the following:

Assistance with errors or unexpected behaviour during installation or development
Addressing product defects as hot-fixes or patches
Compatibility fixes for supported technology platforms.

Therefore if you are on 8.2 or below after December this year then you may need to upgrade to resolve certain issues (depending on what the issues are).

Sitecore 9.0 Features

If you are on 8.2 or below you will also benefit from all the features released in 9.0, here are the key ones:

xConnect – Provides an unified API that centralises data access
Headless CMS support and JSS – Allows web apps to be built with React, Angular, Vue using Sitecore data
Rules based configuration – Configuration is now much simpler as it can be set based on the server role (e.g Content Delivery, Content Authoring)
Sitecore Install Framework (SIF) – SIF is a framework for installing Sitecore using automated scripts. This is how Sitecore 9 and above is now installed and it means deployments can be automated easier.
Sitecore Accelerator Framework (SXA) – SXA is a pre-built set of components to allow pages to be developed quicker with less development effort
Sitecore Forms – Sitecore 9.0 has newly designed forms to replace WFFM. These are built in a modern way and are easier to configure and customise.

Upgrade Considerations

So there are clearly some significant benefits to carrying out an upgrade to Sitecore 9.2, especially if you are on 8.2 still, as some customers are.
There are some additional requirements and considerations when moving to Sitecore 9.2 and standard upgrade considerations which need to be planned for:

Additional Servers / Roles – Due to changes to the architecture to split out elements of Sitecore into smaller services Sitecore 9, 9.1 and 9.2 require some additional Servers and roles. These are for xConnect, Identity Server, Cortex and processing. When you are planning resources for your upgrade this should be considered, particularly on Azure as there are quite a few additional services required.
Module Upgrades – Most Sitecore sites will make use of a number of Modules to extend the out of the box functionality. Some popular modules are: Web Forms for Marketers (WFFM), Url Rewrite and Sitecore Powershell Extensions (SPE). It is important to ensure that each module you are using is supported in Sitecore 9.2 and to consider time for upgrading each module as part of the upgrade process.
Updated Licence – Most customers will require a new licence generating when upgrading to Sitecore 9 and above. Therefore ensure you request this from your account manager in advance and that you have all features/modules you require included on your licence.
Active Directory module – Sitecore 9.1 & 9.2 or later does not support the Active Directory module. Sitecore uses Identity server to handle logins instead of legacy methods such as AD. Therefore if you are upgrading to 9.1 or above and use the AD module you will need to implement an integration with Active Directory from Identity Server.
Search – Sitecore 9 and above no longer supports Lucene so you must use SOLR or Azure Search. Lucene did not work well in distributed search scenarios so moving to SOLR or Azure Search has been recommended for a while. SSL is also required for SOLR in 9.0.
Code & Configuration Updates – Sitecore try and reduce breaking changes where possible but sometimes they are unavoidable, so as with all Sitecore upgrades some custom code and configuration will need to be updated to be compatible with Sitecore 9.2.
To assist with this process Sitecore does provide an Express Migration Tool (to get to 9.0) and an Update Installation Wizard to update to 9.2. However these tools will likely only get you so far for highly customised Sitecore implementations and will likely need some manual upgrading too. Any code that needs upgrading will not be auto-upgraded by the tool. If you are on 8.2 then there are quite a few changes for analytics with xConnect. All references in Visual Studio will need updating to 9.2 also.
Support Patches & Hotfixes – You will likely have some hotfixes or support patches that have been applied to your solution over time. These will need analysing as part of the upgrade to understand if they are still required or not in 9.2. Many of these may have been rolled into 9.2 already.
Analytics Data upgrade – Part of the upgrade process involves migrating xDB data in the 8.x format to Sitecore 9.2 format. Sitecore have a tool for this: https://dev.sitecore.net/Downloads/Sitecore_xDB_Data_Migration_Tool/3x/xDB_Data_Migration_Tool_300.aspx
Implementation Quality – Best practice Sitecore implementations do not customise any out of the box Sitecore files and instead use patch files and extensions to customise configuration and other Sitecore functionality. Ideally the base platform should be installed ‘as is’ and the customisations layered on top to assist with upgradability. Depending on how well your implementation has been carried out will impact how easy it is to upgrade. If your implementation is not best practice then your team should take the time during the upgrade to correct this and take advantage of some of the newer and better ways of doing this.

A Note on Upgrading WFFM

Often one of the key stumbling blocks for upgrading Sitecore to 9.1 or 9.2 is Web Forms For Marketers, this is because it was deprecated in Sitecore 9.1 and is also not supported in Sitecore 9.2. Sitecore 9.0.2 is the last release where WFFM can be used. Sitecore Forms has replaced it. If customers have many forms this can be a bit daunting.

So you could just upgrade to Sitecore 9.0.2 and stop there, but you would be missing out on a lot of features and you will need to upgrade again in the near future. Thankfully there is another option, there is now a community built tool to help automate this for you and convert WFFM forms and data to Sitecore Experience Forms: https://github.com/afaniuolo/WFFM-Conversion-Tool. I have yet to use this but have heard good things about it and it is regularly updated.

I’ve tried to cover the key features of 9.2 and considerations for upgrading here. As you can probably see the longer you leave an upgrade the more complex it becomes as there are more changes to consider. Frequent upgrades of Sitecore should be the aim as this will reduce the time and investment needed to carry them out. Hopefully you’ll find this post useful for planning an upgrade to Sitecore 9.2 and leverage the investment you have made in the platform.