Saturday, November 18, 2017

Sitecore XP 9.0 Local Instance Setup

Sitecore XP 9.0 came up with lot of changes out of which the very noticeable change is the Sitecore setup process.

This blog will help you in setting up and running Sitecore XP 9.0 on your local instance. I have made sure that I cover all the setup steps and procedures that you would need for this. If you need more depth of instruction please follow the Installation guide provided by Sitecore Experience Platform 9.0 Initial Release and please feel free to add your questions and comments on the post.
So let’s get started with Sitecore 9 setup steps.
1.   Requirements to Setup
·       IIS versions:   IIS 10.0 , IIS 8.5
·       Operating System: Windows Server 2016, Windows Server 2012 R2 (64-bit), Windows 10 (32/64-bit) , Windows 8.1 (32/64-bit)
·       .NET Framework Requirements: .NET Framework 4.6.2 or later
·       Visual Studio: Microsoft Visual Studio 2015 or later (targeting .NET Framework 4.6.2)
·       Database: Microsoft SQL Server 2016 SP1, Microsoft SQL Server 2014 SP2
·       Search Indexing: Solr 6.6.1 or later, Lucene, Azure Search
·       Hardware (Single Sitecore Installation):
     4 core processor, 16GB of RAM
     Processor: Intel Pentium 4, 2GHz or faster processor.
     TCP/IP connection at 512Kbps or faster to the Sitecore XP host.
1024 x 768 or greater screen resolution required for advanced operations.      
·      Microsoft PowerShell® version 5.0 or later.
·      Web Platform Installer 5.0. Make sure you install the below software from the web platform.
     Web Deploy 3.6 for Hosting Servers
     URL Rewrite 2.1
     Microsoft SQL Server Data-Tier Application Framework (DAC Fx) version 17.1.
·       Browser: Microsoft Internet Explorer 11 / Mozilla Firefox 54, 55, 56 / Google Chrome 60, 61 / Microsoft Edge 40 / Apple Safari 9, 10, 11
2.   The system I have for the setup of Sitecore XP 9.0 and about which this documents speaks are:
Windows 10, IIS 10, VS 2015 Professional, SQL server 2016 express SP1, SSMS 2017, .Net Framework 4.6.2, Microsoft PowerShell 5.0. SQL Server Management Studio 2017
3.   When you have a system with the required software make sure you do the basic steps before installing any software.
·      Turn Windows features on: Control Panel > Programs > Programs and Features.
            
·        Grant full permissions on “IUSRS” to the temp (%WINDIR%\temp) folder.
         
        

·        Grant full permissions on “Everyone” to the Crypto (%PROGRAMDATA%\Microsoft\Crypto) folder.
        
          


4.   No need to install PowerShell as Windows 10 do come with Microsoft PowerShell 5.0. If you want to check the version of the PowerShell you have then use the command “$PSVersionTable
    
   
5.   Install Web Platform Installer 5.0
      The Sitecore Installation Framework has the following requirements
a.       Web Deploy 3.6 for Hosting Servers
b.       URL Rewrite 2.1
c.       Microsoft SQL Server Data-Tier Application Framework (DAC Fx) version 17.1 x

If the DACFx fails to install, you can see the following error message when using the framework: The SQL provider cannot run with dacpac option because of a missing dependency. Please make sure that DACFx is installed.
        
        
6.   Make sure you have the Java installed or have the latest JRE
7.   Install Visual Studio 2015 Professional and make sure you have the .Net Framework Dev Pack installed and do not forget to install ScriptDom using the installer for Visual Studio (Microsoft SQL Server Transact-SQL ScriptDom).
8.   Setup SOLR 6.6.2
·        Extract the downloaded  zip file to the location C:\solr\
·        Extract NSSM(Not Sucking Service Manager) to the location D:\NSSM\
·        Open PowerShell as an administrator and go to the path in Powershell “D:\NSSM\nssm-2.24\win64” and type command nssm.exe install NameOfSolrService
       
       
·        Set there following values:
Path: C:\solr\solr-6.6.2\bin\solr.cmd   
Startup Directory: C:\solr\solr-6.6.2\bin
Arguments: start -p 8983 -f –v
·        Click Install service button.
          

·        Set the Java_home variable following the below steps.
1.    Right-click the My Computer icon on your desktop and select Properties.
2.    Click the Advanced tab, then click the Environment Variables button.
3.    Under System Variables, click New.
4.    Enter the variable name as JAVA_HOME.
5.    Enter the variable value as the installation path for the Java Development Kit.
6.    Click OK and Apply Changes.


         
            
·        Open services to run the Solr Service installed and verify if it is running.
We have chosen port 8983 so our SOLR instance currently will be available under URL:  http://localhost:8983/solr/

9.   Generate SOLR Certificates
·        Open PowerShell as administrator and go to the path C:\solr\solr-6.6.2\server\etc and run the command.
&'C:\Program Files (x86)\Java\jre1.8.0_141\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=localhostOU=Organizational Unit, O=Organization, L=Location, ST=State, C=Country".
Note: Modify the command with the path of your local keytool.exe. The keypass and storepass are provided as secret, if you want to give a different password then you should replace “secret”. You have to enter this password verification while running the command.
·        Then we need to convert key to PEM format with command:
& 'C:\Program Files (x86)\Java\jre1.8.0_141\bin\keytool.exe' -importkeystore -srckeystore solr-ssl.keystore.jks -destkeystore solr-ssl.keystore.p12 -srcstoretype jks -deststoretype pkcs12
        

·        Download OpenSSL and extract into C:\Program Files (x86)\OpenSSL
·         Run the below command in PowerShell.
& 'C:\Program Files (x86)\OpenSSL\openssl.exe' pkcs12 -in solr-ssl.keystore.p12 -out solr-ssl.pem

Note: For all the password or pass phrase I have entered “secret”
·        To add  the certificate(C:\Solr\solr-6.6.2\server\etc\ solr-ssl.keystore.p12) under trusted root certificates, open mmc
         
        
·        Select Add/Remove Snap-in then Certificates and click on Add button and follow the steps as shown below:
        

        

         
          
              
           
             
             
             

·  Change SOLR settings by adding the below codes in solr.in.cmd file (C:\solr\solr-6.6.2\bin\)
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
REM Require clients to authenticate
set SOLR_SSL_NEED_CLIENT_AUTH=false
REM Enable clients to authenticate (but not require)
set SOLR_SSL_WANT_CLIENT_AUTH=false
·        To verify your SSL certificate restart your SOLR service and browse https://localhost:8983/solr. You can see you solr runing like http.

10.        To verify .Net Framework installed is 4.6.2 or not
·         Open regedit from Run command
          
              
·         Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup and check the Release key.
·        If you have a lower version than that of .Net Framework 4.6.2 then install it.

11.        Install Microsoft SQL Server 2016 SP1 express and SSMS 2017 with Local DB.
·         Right click on the Local DB server > Properties > Advanced
Change the “Enabled contained database” value to True
       
       
          
12.        Install SIF
·        Download Sitecore Install FrameworkSitecore Fundamentals and unblock them once download is complete.
        
               
·        Extract the contents of SitecoreInstallFramework 1.0 rev. 171003.zip and SitecoreFundamentals.1.0 rev. 170922.zip into C:\Program Files\WindowsPowerShell\Modules\.
         
               
·         Open SitecoreFundamentals.psd1 (C:\Program Files\WindowsPowerShell\Modules\SitecoreFundamentals) and edit PowerShellVersion to 5.0 from 5.1.
# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '5.0'
·        Open SitecoreFundamentals.psm1 (C:\Program Files\WindowsPowerShell\Modules\SitecoreFundamentals) and edit the code for PKI as below.
TODO remove the module imports for PKI and WebAdministration.. should be done in module .PSD1
if (!(Get-Module PKI)) { Import-Module }

if (!(Get-Module WebAdministration-or (!(Get-PSDrive IIS -ErrorAction SilentlyContinue))) {
   Get-Module WebAdministration | Remove-Module
   Import-Module
}
·         Run the below command in PowerShell opened as administrator.
Get-Module SitecoreInstallFramework –ListAvailable
        
           
 13.        Setup Sitecore 9 and xConnect.
·      Download the Sitecore 9.0.0 rev. 171002 (WDP XP0 packages).zip file from Sitecore and unblock the zip once downloaded.
·      Extract the contents from Sitecore 9.0.0 rev. 171002 (WDP XP0 packages).zip to the folder C:\Sitecore9XP\. Inside the extracted content in Sitecore9XP folder you will find XP0 Configuration Files rev.171002.zip which you have to extract again inside the Sitecore9XP folder as shown below. The license.xml file is added exclusively for the Sitecore license and install.ps1 is created to have the PowerShell command whose details will be covered in the next steps.
           
              
·       Open PowerShell as administrator and set Execution policy by running the below command and accept it by saying “A” (Yes to ALL).
Set-ExecutionPolicy RemoteSigned
       
      
·         Run the below command also
Register-PSRepository -Name SitecoreGallery -SourceLocation https://sitecore.myget.org/F/sc-powershell/api/v2
       
     
·        Add the below command inside the empty install.ps1.
#define parameters
$prefix = "MyWebsite"
$PSScriptRoot = "C:\Sitecore9XP"
$XConnectCollectionService = "$prefix.xconnect"
$sitecoreSiteName = "dev.sites.local"
$SolrUrl = "https://localhost:8983/solr"
$SolrRoot = "C:\Solr\solr-6.6.2"
$SolrService = "SolrSitecoreXP"
$SqlServer = "(local)"
$SqlAdminUser = "sa"
$SqlAdminPassword="sa"
#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)_xp0xconnect.scwdp.zip"
 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)_single.scwdp.zip"
 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

Note:  define Parameters as per your namings and folder structure followed. The Sql Server parameter should be (local) as your database is pointing to the local DB. Make sure the password and login you have provided in the parameters for the SqlAdminUser and SqlAdminPassword exists and work on your local DB.
·         Run install.ps1 in PowerShell
          
               
·        Open your website/Sitecore on the browser and login with “admin” and password “b”. Voila!! You will be able to see the Sitecore page.

14.        Post installation steps.
·         Open your local DB server, Right click on the server and open new query and on the Query menu click on SQL CMD mode as shown below.
         
               
·        Add the below command in the query and execute
:SETVAR DatabasePrefix SHARDDB
:SETVAR UserName shard
:SETVAR Password sa
:SETVAR ShardMapManagerDatabaseNameSuffix _Xdb.Collection.ShardMapManager
:SETVAR Shard0DatabaseNameSuffix _Xdb.Collection.Shard0
:SETVAR Shard1DatabaseNameSuffix _Xdb.Collection.Shard1
GO
IF(SUSER_ID('$(UserName)') IS NULL)
BEGIN
 CREATE LOGIN [$(UserName)] WITH PASSWORD = '$(Password)';
END;
GO
USE [$(DatabasePrefix)$(ShardMapManagerDatabaseNameSuffix)]
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'$(UserName)')
BEGIN
 CREATE USER [$(UserName)] FOR LOGIN [$(UserName)]
 GRANT SELECT ON SCHEMA :: __ShardManagement TO [$(UserName)]
 GRANT EXECUTE ON SCHEMA :: __ShardManagement TO [$(UserName)]
END;
GO
USE [$(DatabasePrefix)$(Shard0DatabaseNameSuffix)]
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'$(UserName)')
BEGIN
 CREATE USER [$(UserName)] FOR LOGIN [$(UserName)]
 EXEC [xdb_collection].[GrantLeastPrivilege] @UserName = '$(UserName)'
END;
GO
USE [$(DatabasePrefix)$(Shard1DatabaseNameSuffix)]
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = N'$(UserName)')
BEGIN
 CREATE USER [$(UserName)] FOR LOGIN [$(UserName)]
 EXEC [xdb_collection].[GrantLeastPrivilege] @UserName = '$(UserName)'
END;
GO
Note: use a new user name that does not exist in your Local server login.
·        Install Sitecore PowerShell extensions in Sitecore from Sitecore Market place.
·        SXA is free now with Sitecore 9, so why not to go for it then.
·        Rebuild the Search Indexes and the Link Databases.
·        Go to control panel and under Indexing manager Populate Solr Managed Schema.
         
               
·        Then rebuild indexes from the Indexing manager.
·        To deploy marketing definitions go to Sitecore Launchpad, click Control Panel, Analytics, and then click Deploy Marketing Definitions.
         
               

Voila! Our Sitecore setup is done.

5 comments:

  1. This information is really awesome thanks for sharing most valuable information.
    Sitecore Training
    Sitecore Online Training
    Sitecore Training in Hyderabad

    ReplyDelete
  2. Thanks for Amitabh's sharing! But there is error about certificates when I ran the installation scripts.

    Install-SitecoreConfiguration : No registration found for extension 'NewRootCertificate' of type 'Task'.
    At C:\Sitecore\9.0\install.ps1:17 char:1
    + Install-SitecoreConfiguration @certParams -Verbose
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Install-SitecoreConfiguration

    Would you please help me for this!
    Thank you in advanced!
    Sheldon

    ReplyDelete
  3. And below is the content in my xconnect-createcert.json file:

    {
    "Parameters": {
    "CertificateName": {
    "Type": "string",
    "Description": "The name of the certificate to be created."
    },
    "CertPath": {
    "Type": "string",
    "Description": "The physical path on disk where certificates will be stored.",
    "DefaultValue": "c:\\certificates"
    },
    "RootCertFileName": {
    "Type": "string",
    "Description": "The file name of the root certificate to be created.",
    "DefaultValue": "SitecoreRootCert"
    }
    },
    "Variables": {
    // The name dns name of the root certificate.
    "Root.Cert.DnsName": "[concat('DO_NOT_TRUST_', parameter('RootCertFileName'))]",
    // The certificate store for the root certificate.
    "Root.Cert.Store": "cert:\\LocalMachine\\Root",
    // The certificate store for the client certificate.
    "Client.Cert.Store": "cert:\\LocalMachine\\My"
    },
    "Tasks": {
    "CreatePaths": {
    // Create the physical disk path.
    "Type": "EnsurePath",
    "Params": {
    "Exists": [
    "[parameter('CertPath')]"
    ]
    }
    },
    "CreateRootCert": {
    // Create the root certificate.
    "Type": "NewRootCertificate",
    "Params": {
    "Path": "[parameter('CertPath')]",
    "Name": "[parameter('RootCertFileName')]",
    "StoreLocation": "CurrentUser",
    "DnsName": "[variable('Root.Cert.DnsName')]"
    }
    },
    "ImportRootCertificate": {
    // Import the root certificate.
    "Type": "ImportCertificate",
    "Params": {
    "CertStoreLocation": "[variable('Root.Cert.Store')]",
    "FilePath": "[concat(joinpath(parameter('CertPath'), parameter('RootCertFileName')), '.crt')]"
    }
    },
    "CreateSignedCert": {
    // Create a certificate signed by the root authority.
    "Type": "NewSignedCertificate",
    "Params": {
    "Signer": "[GetCertificate(variable('Root.Cert.DnsName'), variable('Root.Cert.Store'))]",
    "Path": "[parameter('CertPath')]",
    "CertStoreLocation": "[variable('Client.Cert.Store')]",
    "Name": "[parameter('CertificateName')]",
    "DnsName": "[parameter('CertificateName')]"
    }
    }
    }
    }

    ReplyDelete