To set up an environment for a Sitecore 9.2 project, we used the Sitecore Installation Framework (SIF) 2.2.0 to create environments on our server and its supporting architecture before any regular deployment process was in place. This involved 6 stages of precise configuration:

  • Creating environments
  • Enabling PowerShell remoting on servers
  • Sitecore Integration Framework
  • Creating an app pool
  • Physical path hardcoding
  • Certificate permissions

Creating environments

To get started we decided to run our environment on separate Content Management (CM) and Content Delivery (CD) environments, as well as the Identity and SOLR servers. We also used XM1 topology due to the complexity of Sitecore XP1. The main difference between XM1 and XP1 is the lack of xConnect.

Improvements to Sitecore Installation Framework 2.0 since its release include pre-built PowerShell scripts which run the bundle of .json files containing SIF commands automatically.

One of these out-of-the-box scripts is the XM1-Distributed.ps1 script. This is a great start but needed additional set-up because it runs on a single computer and executes tasks on many other servers via PowerShell remoting. This is important as it lowers the complexity of spinning up a new XM1 Sitecore instance.

Enabling PowerShell remoting on servers

To enable PowerShell remoting on servers, four key processes were required to configure each of the servers we were planning on deploying to. This included our development environment, the SOLR server and the SQL server.

1. Create a valid computer authentication certificate which cannot be self-signed. Luckily Codehouse has a certification authority capable of generating internally valid certificates. If you have a certification authority you can follow the steps below to generate a computer authentication certificate:

(a) Check for an internally valid certificate by opening ‘certlm.msc’ and checking Personal > Certificates. If there’s a certificate with the ‘Certification Template' of Computer and the ‘Issued To’ field containing the computer’s name, then this has already been set up. If not (most likely) a new one needs to be generated

(b) Generate a computer certificate by right-clicking anywhere in the ‘certlm.msc’ window and selecting All Tasks > Request new Certificate. From here select ‘Next’ and ‘Next’. On the subsequent screen there’s a selection of  certificate types. Tick the box next to ‘Computer’ and expand ‘Details’ then select ‘Properties’

(c) Enter reasonable values using a friendly name and description. Select the tab ‘Subject’ and in the top-most dropdown list choose ‘Common name’. For value, use the fully qualified computer name

(d) Click ‘OK’ and finally ‘Enroll’. A success message about certificate generation is displayed

2. To enable HTTP traffic through ‘winrm’ execute the command ‘winrm quickconfig -transport:https’ on the command line. If this fails it implies the generated computer authentication certificate isn't valid.

3. By default a Firewall Exception for ‘winrm HTTPS’ traffic doesn’t exist so one needs to be created by:

(a) Accessing the ‘Windows Defender Firewall with Advanced Security’ program. Select ‘Inbound rules' and use the button on the right to create a ‘New Rule’

(b) Select the options: Port > Next > TCP > Port 5689 > Next > Allow the Connection > Next > Next. Use a descriptive name like: WINRM HTTPS traffic’> Finish

(c) From the console run the command ‘Enable-PSRemoting’

Sitecore Installation Framework

It’s easy to assume that the correct values are present in the ‘XM1-Distributed.ps1’. Best practice is to check before installation to ensure they are – if they’re not then populate the correct values and then install. Before we get into that below are some 'gotchas' that may help:

  • $SCInstallRoot: This is not referring to a directory on the remote machines but to the directory you’re locally running the script from. For simplicity we used the same directory the ‘Install-XM1-Distributed.ps1’ script was running from
  • $SqlAdminUser: The ‘$SqlAdminPassword’ requires a user with ‘sysadmin’ access to be on the supplied database server. Ensure this aligns with the expected user and make sure the user hasn't got an expired password. You can create a temporary ‘sysadmin’ user for this to run against
  • $allowedCorsOrigins: This should contain the URL of the CM instance (in an XM1 example like this), here you can just use "https://$SitecoreContentManagementSitename"

Creating an app pool

As part of the Sitecore Installation Framework’s scripts an app pool is created for each of the sites (CM, CD, Identity). Depending on your best practices/process the user identity running the apps will vary. At Codehouse we use a dedicated app pool user rather than a generic identity. To set this up in SIF the modification of each of the .json files managing the servers is needed (IdentityServer.json, sitecore-XM1-cm.json, sitecore-XM1-cd.json).

1. In each one of these files look at the task ‘CreateAppPool’. The variables here are supplied in JSON. Ensure that the ‘ProcessModel’ object contains the following fields:

  • 'identityType' as 'SpecificUser'
  • 'userName' as the IIS username
  • 'password' as the IIS password (this can probably be looked at moving into a prompt and variable for the SIF task itself)

2. For the ‘IdentityServer’ an additional property outside of ‘ProcessModel’ called ‘ManagedRuntimeVersion’ may be visible. Do not change the value of this. Below is an example of the code snippet.

Code snippet

Hardcoded physical paths

A minor downside to the Sitecore Installation Framework is that Sitecore provides the scripts with the physical path already hardcoded. This variable is called ‘Site.PhysicalPath’. You can either replace Sitecore's hardcoded value on the C drive with your own hardcoded value or as a future improvement you can look to setting up a SIF parameter to pass in the path.

Certificate permissions

For the Identity Server to run it requires a valid client authentication certificate. Although the Sitecore Installation Framework does an excellent job of generating this certificate, by default our IIS users didn't have access to it. As a result, one of the CM deployment tasks, which is to update the SOLR schema, would regularly fail and prevent the CD steps from ever being reached. Therefore we removed the task ‘UpdateSOLRSchema’ from the CM SIF script (sitecore-XM1-cm.json) with the intention of running this command later. The command itself is ‘{hostname}/sitecore/admin/PopulateManagedSchema.aspx?indexes=all’.

To allow read access to the Client certificate private key locate the ‘CertificateThumbprint’ value in the ‘Client Certificate Thumbprint’ at {IdentityServerPath}\Config\production\Sitecore.IdentityServer.Host.xml.

To access the certificate, open the program ‘certlm.msc’ and search for the thumbprint (the field value should be 'SHA1 Hash’). With the certificate located it's important at this point to make a note of the expiry time, issuer name, etc. as there isn't an easy way of navigating from the search results interface to the certificate.

Assign the private key permissions by right-clicking and selecting All Tasks > Manage Private Keys. Add your IIS app pool user and give ‘Full control’. Finally, give your IIS app pool user ‘Read’ access to the folder '%programdata%Microsoft\Crypto\RSA\MachineKeys'.

Job done! The SIF script is now ready to run.

Find out more about Sitecore Installation Framework (SIF)

For more information on the Sitecore Installation Framework (SIF) and how we can help configure your Sitecore website get in touch.