Overview

There are a few ways to install Sitecore for development purposes. Before Sitecore 9.0, we used Sitecore Instance Manager (SIM). However, since Sitecore has become more advanced and developers want to automate the installation process, Sitecore has introduced the Sitecore Install Framework (SIF) from version 9.0 onwards.

SIF consists of some PowerShell scripts and some JSON configuration files, which makes automation possible.

In addition, SIM 1.6 also includes added support for Sitecore 9.0 – 9.3, and it supports the XM1, XP0 and XP1 topologies.

In this article though, our focus will be using the Graphical Installer (GUI installer) provided by Sitecore since version 9.2.

The Graphical Installer

The GUI Installer referenced in this article was shipped with Sitecore 9.3. There's a new download option for on-premises deployment on the download page. 

Make sure you have logged into the DEV portal and then download the Graphical setup package for XP Single.

The ZIP file contains the following:

This can be grouped like below:

• JSON configuration files

• Sitecore WDP packages (ZIP files)

• PowerShell script

• Setup.exe and its configuration file: setup.exe.config

In addition to the above, you need to have a compatible SQL server running beforehand. The installer ZIP file doesn't contain everything (for example, Solr and SIF) but it will guide you through the installation process.

JSON configuration files

Although this is a graphical installer, it utilises Sitecore SIF. These JSON files are passed to SIF by the installer, which typically calls the Install-SitecoreConfiguration Powershell cmdlet supplied by Sitecore SIF and passes the required parameters.

The JSON files are self-explanatory from their names. For example, createcert.json would be used to perform some tasks related to certificates like IdentityServer.json, which installs the Identity Server; and so on.

WDP packages

The *.scwdp.zip files are the Web Deployment Packages (WDPs) used during the installation process when installing xConnect, Identity Server, Sitecore, etc. They require Microsoft WebDeploy to work, which will be installed as one of the perquisites.

PowerShell Script

There's only one shipped with the installer: XP0-SingleDeveloper.ps1. This file is useful, however, it's not used by the installer itself. The installer calls Sitecore SIF directly. We'll come back to this file later.

The Setup.exe

This is the main entry point of the GUI installer. This will be used throughout the installation process. The setup.exe.config is important for installation customisation.

Installation and customisation

While the OOTB installer works, there are few things to change to suit company needs, for example, naming conventions, install locations, etc.

One of the most disliked behaviours the earlier version of the installer did was to hardcode the install location to be under C:\inetpub\wwwroot.  Ensure to keep the C drive free for system files and important software essential for our daily work.

OOTB installation

The installer requires a local SQL admin account, so make sure you have one. Despite the installer can install the perquisites, you still need an existing running SQL server. The officially Sitecore 9.3 supported version is from QL 2016 SP2 to SQL 2019.

Before the GUI installer worked, we needed to manually run the PowerShell script and update the parameters. We also installed various perquisites before the installation can be successful. The GUI installer eliminates all that and provides an all-in-one tool for installing Sitecore. When we run the setup.exe, we see the welcome screen as below:

The installer includes several steps, as you can see from the left-hand side of the installer after clicking Start:

Prerequisites step

If you’ve never installed Sitecore 9.3 before, make sure you click Install to install these perquisites. Otherwise, click Skip to go to next step.

Because the installer is just a SIF wrapper, Sitecore SIF is required.

The other perquisites the installer checks and installs are:

• Visual C++ 2015 Redistributable

• SQL Server Powershell Module

• Windows Features, e.g. IIS

• Web Platform Installer

• WebDeploy

• IIS UrlRewrite Module

• SQL CLR Data Types

• SQL Data-Tier Application Framework (DacFx)

• SQL ODBC Driver

• .NET Core Hosting

• .NET Framework

Look at the Prequisites.json file for more details.

Install Solr step

This step has prepopulated the fields. Modify it to suit your environment. These values will be used in a later step so ensure they're completed whether you're installing Solr or not.

The Windows service and path prefix is usually the abbreviation of your project. This value will be used to prefix your Solr cores, windows services and the physical Solr installation folder.

If you need to install Solr, review and update the fields and then click Install.

If you're using an existing Solr instance, you must have a compatible version (the officially supported version for Sitecore 9.3 is Solr 8.1.1) running locally

In this case, ensure the values are correct and click Skip to continue.

Sitecore settings step

By default the field values on this step are blank. The Installation/solution prefix is usually the same as the Windows service and path prefix from the previous step for consistency.

The prefix will be used for prefixing the SQL databases, windows services, website hostnames, etc. Complete the fields and proceed to the next step.

SQL server settings

By default, it uses a local SQL instance with the SA SQL account. As mentioned earlier, we've used the scinstaller account instead. Proceed to the next step once you're ready.

Solr settings step

This step prepopulates the fields according to the values from the Install Solr step. Review and update if needed. Proceed to the next step when ready.

Optional modules step

This is a new step in Sitecore 9.3 GUI installer. It allows you to install additional Sitecore modules if needed. The only option for now is the Sitecore Experience Accelerator (SXA). Tick the box if you wish to install SXA along with Sitecore and then proceed to the next step.

Summary step

This step shows a summary of all the values entered earlier. Review all of them and use the Back button to amend the field values from previous steps as needed. Otherwise, proceed to the next step.

Validate step

This step validates the license file, JSON configuration files and all the required Sitecore WDP packages.

You’ll only be able to continue if all of them passed the validation. Click Install to start the installation.

The installation usually takes around 20 minutes. You'll see the success message below when completed:

Click Next to finalise/confirm installation:

Either Close the installer or click on the Launch Sitecore button to browse to the Sitecore backend through the local Identity Server installed during the installation.

Summary of the OOTB installation

The installation can be categorised into several parts.

• Websites

• Website physical location

• Solr

• Solr cores

• Windows services

• SQL databases

• SSL certificates

Websites

The installer (XP0 Single) installs the following websites, or web applications:

• Identity Server: https://sc930identityserver.dev.local

• xConnect: https://sc930xconnect.dev.local

• Sitecore: https://sc930sc.dev.local

Note that the site hostnames are prefixed with the prefix entered in the Sitecore settings step (i.e. sc930) during the installation and post-fixed with “.dev.local”. Depending on the role, it also prefixes the hostnames with identityserver, xconnect or sc. The hostnames are added to the hosts file as well.

Website physical location

Websites are installed under C:\inetpub\wwwroot within their own folder. For example:

Solr

If you've chosen to install a new Solr instance, the installer basically follows what you specified in the Install Solr and Solr settings steps. It creates the Solr windows service and a Solr instance folder to store the Solr cores and configurations.

Solr cores

The Solr cores will be prefixed with the prefix specified in the Install Solr step followed by an underscore and the various Sitecore index names. For example, sc930_web_index.

Windows services

Sitecore 9.3 xConnect installs three windows services:

• Marketing Automation: c930xconnect.dev.local-MarketingAutomationService

• Processing Engine: sc930xconnect.dev.local-ProcessingEngineService

• Index Worker: sc930xconnect.dev.local-IndexWorker

Note that the naming convention follows similar rules as the website hostnames, with the service type appended at the end.

SQL databases

The SQL databases are also prefixed in a similar manner. For example, sc930_Core.

SSL certificates

The installer creates required self-signed SSL certificates for Solr, xConnect (server and client) and Sitecore. These are locally trusted.

Customisation

Every company has their own standards, such as naming conventions, preferred location of files, etc. The GUI installer is developed in a very flexible way and it’s configuration file will be the first thing to look at when it comes to customisation.

The setup.exe.config file

In this config file you'll see a set of templates:

Each template has a name, a path to the JSON file and its parameters.

If you know how SIF works before, this will be familiar because SIF requires a JSON file and a set of parameters.

The Prerequisites template doesn't require any parameters because it just installs software and configures windows. It's called when you click Install in the Prerequisites step from the installer.

Let’s take a closer look at the Solr template from the screenshot. What does it tell us?

• The name is “Solr”

• It uses a configuration file called “\Solr-SingleDeveloper.json”

• It has three parameters: SolrPort, SolrServicePrefix, SolrInstallRoot

• The three parameters have the same groupName called “InstallSolr”

If we now match this with the fields on the Install Solr step in the GUI installer, they are exactly the same.

We'll explore this more in the XPSingle template later. Before that, let’s examine at how a parameter is used.

Template parameters

Each template parameter has the following attributes:

• name (mandatory)

• type

• groupName

• value

A parameter maps to a field in the GUI Installer if it makes sense.

Name

Remember that a template points to a JSON file? Notice the Solr-SingleDeveloper.json file has the same parameters as those in the Solr template.

Be aware that XML and JSON are both case-sensitive. So, if you want to pass something to the JSON file, which then gets picked up by SIF, you can define a template parameter and also make that parameter available in the corresponding JSON file.

Type

The type attribute determines how the parameter looks in the GUI Installer. By taking a look at the whole config file, it supports “text”, “filePath” and “password” field types, that renders a text box, a file browser, and a password text box respectively. This isn't required if you just want to set a parameter with a fixed value.

Group name

The groupName attribute determines, in which step, the parameter (a field) appears in the GUI Installer.

Below is a mapping of groupName to the steps in the GUI:

• InstallSolr: Install Solr step

• Sitecore: Sitecore settings step

• Sql: SQL Server settings step

• Solr: Solr settings step

If you don't specify a groupName, that parameter will not appear in the UI. And if you add a new parameter and specify it an existing groupName, it WILL appear in the UI and you can change the value directly from the UI.

Any new parameter added in the config that appears in the UI.

Value

The value attribute allows specifying a default value of the parameter. Instead of a static value, it also supports a dynamic value based on the value of other parameters.

To bind a value from another parameter, use the format {templateName.ParameterName}. For example, if a parameter value in the XPSingle template needs something from a previous step, Solr for example, you use something like value=”https://localhost:{Solr.SolrPort}/solr”. When you navigate to the relevant step that the parameter is defined, it will be prepopulated with the desired value.

The XPSingle template

The first thing we want to customise is the default installation location, which goes to “C:\inetpub\wwwroot”. This requires an understanding of the various JSON files. These are controlled by a JSON parameter called SitePhysicalRoot. If this parameter is empty, it will use “C:\inetpub\wwwroot”. So, how can it be changed?

Neither the UI nor the setup configuration has defined this. This can be added manually.

In the XPSingle template, add the following parameter (remember, it's case-sensitive):

parameter name="SitePhysicalRoot" type="text" groupName="Sitecore" value="D:\WebApplications"

Start the installer and proceed to the Sitecore settings step. A new field now appears:

If changed, the UI will remember this in the same session.

Any parameters added to the template that appear on the UI (i.e. has a groupName), will also be picked up in the Summary step, so you can review them all.

Customisation summary

The JSON files are outside the scope of this document, however, we have described how the UI links to the JSON files by defining templates and passing parameters.

You can add any parameters, as long as they match each other in the setup configuration file and the JSON file you are calling.

One example the Codehouse development team implemented was that because the OOTB installer doesn't support using a custom IIS application pool user, we added additional parameters to make them appear in the UI. This was so the developers can specify a different application pool user for different Sitecore websites being built.

The Codehouse development team also customised the install location to group sites more precisely, instead of dumping all sites from all projects flat in a big folder. For example:

SitePhysicalRoot

• client1: client1.local, client1-is.local, client1-xc.local

• client2: client2.local, client2-is.local, client2-xc.local

Uninstall Sitecore

As mentioned earlier, the XP0-SingleDeveloper.ps1 is not used if you're using the GUI installer. However, it becomes useful in case you need to uninstall Sitecore. For example, if the installation unexpectedly fails halfway.

The PowerShell script supports both install and uninstall, but the uninstall part is commented out by default. To make this file more useful, we customised it to accept a parameter called Uninstall.

At the top of the file, add the following:

To uninstall Sitecore, make a custom copy of the XP0-SingleDeveloper.ps1 and update the variables to match your particular project. For example, Prefix, Solr related variables, etc. Then run it with the Uninstall parameter in an elevated PowerShell window. This removes:

• Solr cores (not Solr itself)

• SQL databases

• Windows services

• IIS Websites and application pools

• Physical website folders

Working with Codehouse

As Sitecore experts we specialise in upgrades. If you're running older versions of Sitecore and are interested in upgrading your solution then get in touch.