Getting Up and Running with Sitecore 9

This post serves to get you up and running quickly on a local instance of the newly released Sitecore 9. If you don't feel like reading the whole thing - use the links below to jump to the section that interests you.

SQL Database Configuration
SOLR Setup
Install SIF and Sitecore Fundamentals
Install XConnect and Sitecore
Post-Install Steps

As Sitecore enthusiasts will no doubt be aware, Sitecore 9 was released recently and comes with a host of new features. I could probably go into some depth about these but will leave it to you to read the lowdown from the one-and-only JammyKam.

The biggest change is XConnect which separates out Xdb related functions into a separate layer  enabling collection of analytics data from a wider variety of sources such as mobile apps, IOT sensors, third party apps etc. More information on XConnect can be found here.

Another big change (no doubt influenced by XConnect) that you will face when downloading Sitecore 9 is how / where to start. Gone is the fairly simplistic Installation Wizard and in comes a new way to install Sitecore via PowerShell. Instead of downloading and running an installer that does most things for you - you have to download a combination of PowerShell Modules, JSON configuration scripts and Web Deploy Packages. It should be noted that there is still the option of downloading a zip of the installation and manually setting up everything!

So what do these new installation components do?

Powershell Modules. Before you can do anything, you must install the Sitecore Installation Framework and Sitecore Foundation modules. These will introduce Sitecore related commandlets that you can use to install and configure your Sitecore instance. I can't say I know too much about the goodies in here at this point (note to self: read the manual!)

JSON Configuration Scripts. These are contained in the Configuration Files zip of your chosen package. Sitecore have provided different sets of scripts according to the topology of your environments. For example, single instance with experience platform (XP0), CM only (XM1) etc. Within these scripts you can set default parameter values if you choose to. Note: there is not a single JSON script but a set of them according to the configuration you choose. When running a configuration commandlet you pass the path of a JSON configuration file in order to set up the parameters used by that commandlet.

Web Deploy Packages. As well as the Configuration Files zip you will also find zips for web deploy packages relating to XConnect and the Sitecore instance itself. These will be extracted and installed as part of the installation process.

Before We Begin

Okay so I could go on and on in detail but let's make a start. First things first - make sure you've got all the required software and hardware. For my developer laptop - I've got the following:

  • Windows 10 64-bit (read the manual for other supported versions)
  • IIS 10. IIS Version 8.5 will also work but the manual also says Sitecore Fundamentals will not work with IIS 8.5 - I'm not sure why!
  • .Net Framework version 7 (Sitecore XP 9 requires a minimum of version 4.6.2)
  • Visual Studio 2015 (targeting .net 4.6.2 or above)
  • SQL Server 2017 Developer Edition (Sitecore supports SQL 2016 SP1 upwards). Note, Sitecore XP 9 does not currently support MongoDB or Oracle DBs - support will be coming in later versions.
  • Web Platform Installer 5
  • Web Deploy 3.6 for Hosting Servers
  • SQL DAC Fx 17
  • MSSQL Transact SQL ScriptDom (installed via Visual Studio). This was already installed with my Visual Studio.
  • SOLR 6.6.1 with SSL support. Note Lucene is not supported by XConnect so it's time to embrace SOLR and say goodbye to Lucene :) More on installing SOLR in a bit.
After you've got the required software in place - it's time to do some basic configuration.

Enable Contained DB Authentication

Since Powershell will provision SQL users - we need to enabled Contained Database Authentication mode on SQL Server by executing the following SQL:

sp_configure 'contained database authentication', 1;

Setup SOLR

As mentioned SOLR is being preferred in place of Lucene for XP 9. So here's a quick guide to getting SOLR ready. It is by no means a definitive guide! Before proceeding ensure you have installed the latest Java Runtime Environment (I have v1.8) and setup your JAVA_HOME and PATH environment variables to point to the relevant Java directories.

1. Download the SOLR 6.6.1 zip (not tar) and save. Unblock the zip after download is complete.

2. Extract the solr-6.6.1 folder within the zip and copy it to C:\. So the location of SOLR is essentially C:\solr-6.6.1.

3. Open a elevated privilege command prompt window and navigate to c:\solr-6.6.1\bin and enter the following command to start SOLR:

solr start-p 8984

4. Enter the following command to stop SOLR:

solr stop -p 8984

5. Download and save this nifty solrssl.ps1 script from Kamsar to create a SSL certificate for SOLR. SSL is required by XConnect when connecting to SOLR.

6. Run the script in step 5 as follows from the location where you saved it via Powershell or an elevated command prompt.

.\solrssl.ps1 -KeystoreFile C:\solr-6.6.1\apache-solr\server\etc\solr-ssl.keystore.jks

7. Edit C:\solr-6.6.1\bin\ and paste the following at the end of the file and then save and exit the file:

set SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks
set SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks

8. Start SOLR as per step 3 and browse to https://localhost:8984/solr. If all has gone well - you should see the SOLR dashboard page with a valid SSL certificate.

Now that we have housekeeping out of the way. It's time to get started with Powershell.

Install SIF and Sitecore Fundamentals.

To install new Sitecore 9 instances we will need to make use of the Powershell commandlets that are provided by Sitecore via the Sitecore Install Framework and Sitecore Fundamentals modules. More information about these can be found on the Sitecore Documentation site.

1. Download these zips: Sitecore Install Framework, Sitecore Fundamentals and unblock them once download is complete.

2. In File Explorer create SitecoreInstallFramework and SitecoreFundamentals folders within the  C:\Program Files\Powershell\Modules folder.

3. Extract the contents of SitecoreInstallFramework 1.0 rev. into C:\Program Files\Powershell\Modules\SitecoreInstallFramework

4. Extract the contents of SitecoreFundamentals.1.0 rev. into C:\Program Files\Powershell\Modules\SitecoreFundamentals

5. Using the above method ensures the modules are available to all users of your machine. This should hopefully mean that you won't need to use the Import-Module command.

6. Validate the module install by running the following command in an elevated PowerShell window:

Get-Module SitecoreInstallFramework –ListAvailable

7. The above command should produce the following result:

Installing XConnect and Sitecore

So far we've only been laying the groundwork. Now it's time to build on that and spin up XConnect and Sitecore.

1. From the Sitecore 9 download page click Packages for XP Single link from Sitecore to download the Sitecore 9.0.0 rev. 171002 (WDP XP0 packages).zip file. Unblock the zip once downloaded. To make it easier - you can extract the contents a dedicated folder eg. Sitecore9_packages. See below image for an idea of the files contained within:

2. Assuming you've extracted the file files contained in the zip to Sitecore9_Packages folder, extract the contents of XP0 Configuration Files to Sitecore9_Packages. This should result in folder contents as per the image below - however, please note that I dropped in the Sitecore License.xml file and install_sitecore.ps1 script at a later point so don't be confused by this :)

At this point you should have a bunch of JSON files in your Sitecore9_packages folder and like me - you are probably wondering how to start installing. Firstly - know that you can and probably should edit some of these files to change default values for some parameters like SQL Prefix, SQL Usernames / passwords and SOLR details. For the most part I've kept it vanilla so haven't changed much.

Reading through the manual - you can see that you can run the following PowerShell command to install stuff by passing it a JSON config file. However, what was not obvious to me is the order in which things had to be installed for example - you need to have SSL certificates for XConnect setup.

Install-SitecoreConfiguration –Path C:\Sitecore9_Packages\sitecoreXP0.json

After further investigation - I found that there is a PowerShell script that installs elements in order and makes the process more transparent. The script allows us to setup some default parameter values first before it executes specific setup tasks. So in short, it's easier to create the script below (you will still need the JSON files extracted earlier). All you really need to do is set the parameters at the top of the script and then run it in order to create a XConnect and Sitecore instance. For my example I have saved the script as install_sitecore.ps1. The contents are below - simply change the default parameter values near the top of the script and run the script in PowerShell to start installing Sitecore. Ensure that SOLR is running!

#define parameters
$prefix = "SC9DemoXP0"
$PSScriptRoot = "C:\Sitecore9_Packages"
$XConnectCollectionService = "$prefix.xconnect"
$sitecoreSiteName = "$"
$SolrUrl = "https://localhost:8984/solr"
$SolrRoot = "C:\Solr-6.6.1"
$SolrService = "Solr-6.6.1"
$SqlServer = ".\MSSQL2017"
$SqlAdminUser = "SQLUSER"

#install client certificate for xconnect
$certParams = @{
 Path = "$PSScriptRoot\xconnect-createcert.json"
 CertificateName = "$prefix.xconnect_client"
Install-SitecoreConfiguration @certParams -Verbose

#install solr cores for xdb
$solrParams = @{
 Path = "$PSScriptRoot\xconnect-solr.json"
 SolrUrl = $SolrUrl
 SolrRoot = $SolrRoot
 SolrService = $SolrService
 CorePrefix = $prefix
Install-SitecoreConfiguration @solrParams

#deploy xconnect instance
$xconnectParams = @{
 Path = "$PSScriptRoot\xconnect-xp0.json"
 Package = "$PSScriptRoot\Sitecore 9.0.0 rev. 171002 (OnPrem)"
 LicenseFile = "$PSScriptRoot\license.xml"
 Sitename = $XConnectCollectionService
 XConnectCert = $certParams.CertificateName
 SqlDbPrefix = $prefix
SqlServer = $SqlServer
SqlAdminUser = $SqlAdminUser
 SqlAdminPassword = $SqlAdminPassword
 SolrCorePrefix = $prefix
 SolrURL = $SolrUrl

Install-SitecoreConfiguration @xconnectParams

#install solr cores for sitecore
$solrParams = @{
 Path = "$PSScriptRoot\sitecore-solr.json"
 SolrUrl = $SolrUrl
 SolrRoot = $SolrRoot
 SolrService = $SolrService
 CorePrefix = $prefix
Install-SitecoreConfiguration @solrParams

#install sitecore instance
$xconnectHostName = "$prefix.xconnect"
$sitecoreParams = @{
 Path = "$PSScriptRoot\sitecore-XP0.json"
 Package = "$PSScriptRoot\Sitecore 9.0.0 rev. 171002 (OnPrem)"
 LicenseFile = "$PSScriptRoot\license.xml"
 SqlDbPrefix = $prefix
SqlServer = $SqlServer
SqlAdminUser = $SqlAdminUser
 SqlAdminPassword = $SqlAdminPassword
 SolrCorePrefix = $prefix
SolrUrl = $SolrUrl
 XConnectCert = $certParams.CertificateName
 Sitename = $sitecoreSiteName
 XConnectCollectionService = "https://$XConnectCollectionService"
Install-SitecoreConfiguration @sitecoreParams

As you can see from the script above, the order is:

1. Install client certificate for XConnect,

2. Install Xdb cores for SOLR

3. Install XConnect instance (IIS site + DBs + Services)

4. Install SOLR cores for Sitecore (ie. indexes for master, core, etc.)

5. Install Sitecore instance (IIS Site + DBs)

Once you run the above script the installation tasks will be carried out in sequence.

Assuming you've set the parameters correctly - you should see the PowerShell screen whiz by frantically installing and updated various things. After around 5 minutes the installation should be complete depending on your computers horsepower. You should see the screen below - however, there's more to do:

As you can see above - there is a log file generated which you can examine for issues. We are now ready to do some post-install tasks before we're done.

Post-Install Tasks.

1. Add Recognised SQL User to XDB Shards. In order to do this we need to run the SQL script below. Note we must use SQL CMD mode via the Query menu of SQL Management Studio. Ensure that you change the DatabasePrefix, UserName and Password fields to suit your setup (cross reference against JSON config files).

:SETVAR DatabasePrefix SC9DemoXP0
:SETVAR UserName collectionuser
:SETVAR Password Test12345
:SETVAR ShardMapManagerDatabaseNameSuffix _Xdb.Collection.ShardMapManager
:SETVAR Shard0DatabaseNameSuffix _Xdb.Collection.Shard0
:SETVAR Shard1DatabaseNameSuffix _Xdb.Collection.Shard1
IF(SUSER_ID('$(UserName)') IS NULL)
 CREATE LOGIN [$(UserName)] WITH PASSWORD = '$(Password)';
USE [$(DatabasePrefix)$(ShardMapManagerDatabaseNameSuffix)]
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'$(UserName)')
 CREATE USER [$(UserName)] FOR LOGIN [$(UserName)]
 GRANT SELECT ON SCHEMA :: __ShardManagement TO [$(UserName)]
 GRANT EXECUTE ON SCHEMA :: __ShardManagement TO [$(UserName)]
USE [$(DatabasePrefix)$(Shard0DatabaseNameSuffix)]
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'$(UserName)')
 CREATE USER [$(UserName)] FOR LOGIN [$(UserName)]
 EXEC [xdb_collection].[GrantLeastPrivilege] @UserName = '$(UserName)'
USE [$(DatabasePrefix)$(Shard1DatabaseNameSuffix)]
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'$(UserName)')
 CREATE USER [$(UserName)] FOR LOGIN [$(UserName)]
 EXEC [xdb_collection].[GrantLeastPrivilege] @UserName = '$(UserName)'

Upon executing the script you should see the following in the messages window:

2. Rebuild Search Indexes. Log into your Sitecore instance and rebuild the indexes via Indexing Manager.

3. Rebuild Link Databases.

4. Redeploy Marketing Definitions. This will make use of the new XConnect service layer to deploy marketing definitions to Xdb. This may take around 20 minutes depending on how busy your computer is.

5. Other post-install steps. There are other steps outlined in the manual such as configuring Content Expiration and Geo-IP tracking which you should look into but I will not highlight here.


So by now - you should have Sitecore and XConnect setup and ready to go. However, it's also worth looking at how the pieces fit together.

IIS sites created for Sitecore and XConnect - notice the AppData folder now contains what was originally in the Data folder such as logs, diagnostics, packages etc..

SQL Databases. It's worth nothing that access to Xdb databases is via the XConnect service - not directly.

New services added for XConnect and Marketing Automation Engine on a per instance basis:

Finally - one thing you may notice is that if you browse to the XConnect website instance - you may not see anything. This is because (as far as I know) - XConnect does not have a UI.

Hopefully you will have found this guide useful in getting started with Sitecore 9. I'm sure I've probably missed some details so if you notice any errors / inaccuracies / downright lies - please do feel free to correct me :)


Popular posts from this blog

Alexa and Sitecore Integration - Part 3

Alexa and Sitecore Integration using OData and XConnect