Installing Sitecore 9 when you’ve installed 9.1

Installing Sitecore 9 was never the easiest of things, particularly when you compare it to how relatively simple Sitecore 8 was. But if you install Sitecore 9.1 on the same machine and then try your trusty Sitecore 9.0 script you may find it’s got even harder and there’s a bunch of new issues to worry about.

Multiple version of SIF

The first issue your probably going to run into is an error saying a name parameter is missing. Your script hasn’t change, but what has changed is the default version of SIF that’s now running.

So the first change you need to make is to ensure your running the correct version of SIF. You can do this either by adding the command to your script or running this before calling you install script. It will take effect for the duration of your PowerShell session.

#Switch to correct vesion of SIF
Remove-Module -Name SitecoreInstallFramework
Import-Module -Name SitecoreInstallFramework -RequiredVersion 1.2.1

If you want to check what the active version of SIF is you can do this in a PowerShell window using

Get-Command -Module SitecoreInstallFramework | Select-Object -Property name, version

Certificates Error – Part 1

Now we’re calling the right version of SIF, the next issue I encountered was to do with certs. Specifically I got this error:

TerminatingError(New-SignedCertificate): "Cannot process argument transformation on parameter 'Signer'. Cannot convert the "System.Object[]" value of type "System.Object[]" to type "System.Security.Cryptography.X509Certificates.X509Certificate2"."
Install-SitecoreConfiguration : Cannot process argument transformation on parameter 'Signer'. Cannot convert the "System.Object[]" value of type "System.Object[]" to type "System.Security.Cryptography.X509Certificates.X509Certificate2".

This is due to the certificate for Sitecore 9.1 that has been installed. You can remove the certificate but then your Sitecore 9.1 install will break instead.

Alternatively add a “RootCertFilename” to the certificate definition:

# Install client certificate for xconnect
$certParams = @{
  Path = "$SCLocation\xconnect-createcert.json"
  CertificateName = "$prefix.xconnect_client"
  RootCertFileName = "SIF121Root"
}
Install-SitecoreConfiguration @certParams -Verbose

Certificate Error – Part 2

This error looks exactly the same as the error above but you’ve already added that Root Cert File Name, so what’s happening now.

Install-SitecoreConfiguration : Cannot process argument transformation on parameter 'Signer'. Cannot convert the
"System.Object[]" value of type "System.Object[]" to type
"System.Security.Cryptography.X509Certificates.X509Certificate2".
At C:\resourceFiles9.0\install.ps1:47 char:1
+ Install-SitecoreConfiguration @certParams -Verbose
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Install-SitecoreConfiguration

The error is saying that it expected to find 1 certificate but found many instead. Each time you run the script the number of thumbprints also keeps going up.

TBH I’m not overly certain what causes this as most of the time you get the one root cert and your done forever more. But somehow you get a second and then get you in a loop of repeatedly deleting certificates only to discover they still exist somewhere. You know it’s also not the certificate for the 9.1 install as the certificate has the new name you added to it.

For me the issue was although I had deleted them from my personal certificates, trusted root certificates, and even the c:\certificates folder they were being added to, what I needed to do was run this in powershell.

 Get-ChildItem -Path "cert:\LocalMachine\Root" | Where-Object { $_.subject -like "*SIF121Root*" }
  | Remove-Item

If your wanting to find out what certificates are installed on your machine you can run these

Get-ChildItem -Path "cert:\LocalMachine\Root" | Format-Table Subject, FriendlyName, Thumbprint
Get-ChildItem -Path "cert:\LocalMachine\My" | Format-Table Subject, FriendlyName, Thumbprint
Get-ChildItem -Path "cert:\CurrentUser\My" | Format-Table Subject, FriendlyName, Thumbprint

Make sure your config is actually correct

This one is really just my mistake. Multiple versions of Siteocore have meant rather than just having one “C:\reousrcefiles\” folder on my machine (as per instructions), I now have a few with the version post-fixed to the end. It only becomes apparent that the path in the install.ps1 file is wrong part way through the install process.

Sitecore 9 installation tips

Sitecore 9 released this week and with it comes a whole new installation process. Gone are the days you could just download the web root and restore some dbs or just run the installation gui and enter a db connection string. Sitecore 9 has some fairly fundamental architectural changes with multiple IIS entries and and some windows services to go with it. Server roles are now also being properly configured rather than updating config files to match what it says in an excel doc.

Along with these changes, the installation process has moved to be based on powershell scripts, which on one hand has made things a bit harder, but it also brings great positives that the process can now be customized with scripts that are repeatable without the risk of mistakes.

Here’s my tips for a smooth local installation (production installs are different to a local install).

Tip #1 – Check the Prerequisites and Requirements

It sounds obvious but when presented with a new toy you want to play with it as fast as possible, and with a 49 page document the urge is there to skip to the installation and hope for the best.

Skipping however is likely to result in install failures as the installer relies on modules such as Web Deploy and the right version of SQL Server which were not needed for the version you may already have installed.

Tip #2 – Make sure you have the right versions

You may have SQL and Solr but are they the right version?

SQL Express 2016

Sitecore 9 supports SQL Server 2014 SP2 and SQL Server 2016. Now that SQL Server 2017 is out, actually finding the link for 2016 express has become a challenge, but here it is.

Download SQL Server 2016 Express

Solr 6.6.1

Sirecore 9 supports Solr version 6.6.1. I typically use Bitnami Solr as it’s a lot easier to install than doing Solr on it’s own. Like SQL though the latest version is newer than what Sitecore supports and finding the link to the older one can be a bit of a challenge.

Download Bitnami Solr 6.6.1

Tip #3 – Solr requires SSL

By default Solr does not install with SSL turned on, but without it your install will fail. More specifically it will fail trying to start an xConnect service.

Enabling SSL for Solr

To create a self-signed certificate for Solr we can use the JDK Keytool which if you’ve installed Solr you should already have installed.

Note: These instructions are based on this guide from Apache and this blog post from Jason St-Cyr.

  1. Open command prompt
  2. Change to the Solr ‘etc’ directory
    cd "{SOLR_HOME}\server\etc"
  3. Execute the keygentool command
    "{JAVA_HOME}\bin\keytool.exe" -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 -keypass secret -storepass secret -validity 9999 -keystore solr-ssl.keystore.jks -ext SAN=DNS:localhost,IP:127.0.0.1 -dname "CN=localhost, OU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country"

    This will generate the keystore with a password of ‘secret’ as valid for localhost and 127.0.0.1. You can add other DNS and IPs as desired, or skip hostname verification.

  4. Convert generated JKS to PKCS12
     "{JAVA_HOME}\bin\keytool.exe" -importkeystore -srckeystore solr-ssl.keystore.jks -destkeystore solr-ssl.keystore.p12 -srcstoretype jks -deststoretype pkcs12
  5. Enter password when prompted. The password ‘secret’ was used in the previous step. Remember to use your password instead if you changed it in the keygen command parameters.
  6. Open Windows Explorer and navigate to the ‘etc’ directory (“{SOLR_HOME}\server\etc”)
  7. Double-click on the generated ‘p12’ file (solr-ssl.keystore.p12 if you used the default parameters from the previous steps)
  8. In the wizard, specify the following values (there will be some extras you can ignore):
    • Store Location: Local Machine
    • File name: Leave as provided
    • Password: secret
    • Certificate Store: Trusted Root Certification Authorities

    Remember to use your password instead if you changed it during the previous steps.

  9. Open the solr.in.cmd file for editing (e.g. {SOLR_HOME}\bin\solr.in.cmd)
  10. Un-comment the SSL settings:
    set SOLR_SSL_KEY_STORE=etc/solr-ssl.keystore.jks
    set SOLR_SSL_KEY_STORE_PASSWORD=secret
    set SOLR_SSL_TRUST_STORE=etc/solr-ssl.keystore.jks
    set SOLR_SSL_TRUST_STORE_PASSWORD=secret
    set SOLR_SSL_NEED_CLIENT_AUTH=false
    set SOLR_SSL_WANT_CLIENT_AUTH=false

    Remember to update passwords and file paths to match to the parameters you specified.

  11. Restart SOLR to pick up the changes.

Tip #4 – Close management studio

I’m not sure if this was a one off thing, but with management studio open my installation failed with a single user access issue.

Tip #5 – Check the logs

The installation script will output logs to the folder it runs in. If your installation fails it will reference a log file. To find out why the installation failed or get some more info go and check the log referenced.