commerce

Sitecore Commerce 9 Update 2 and Step-by-step Install Guide on your machine

This one is a summary of my own experience for Sitecore Experience Commerce 9 Update 2 (aka Sitecore XC 9.0.2) installation on my machine. I’ve had much experience in Sitecore XC9 installation and Sitecore XC9 Update 1 installation so I decided to go only with:

I do hope that this blog post is helpful for your own journey as well.

Setup Prerequisites

Step-by-step guide

  1. install the ones below if not yet 😀
  2. rebuild the Link databases for the master and core databases if not yet:
    • on the Sitecore Launchpad, click Control Panel, and in the Database section, click Rebuild Link Databases
    •  select the master and core databases and then click Rebuild
    • sc9com_1
  3. rebuild the search indexes if not yet:
    • on the Sitecore Launchpad, click Control Panel, and in the Indexing section, click Indexing manager
    •  in the Indexing Manager dialog box, click Select all, and then click Rebuild
    • sxc902_7
  4. DO NOT stop the xConnect site sc9com.xconnect.local
    • from the installation guide with love (Page 9)
    • sxc902_6
  5. create a new folder E:\sc9_com_install
  6. create a certificate for the Sitecore Commerce Engine Connect to authenticate with the Sitecore XC Engine:
    • launch PowerShell as an administrator
    • create the certificate by running the following cmdlet:
      • New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname “storefront.local”
    • export the certificate to a file by running the following cmdlet:
      • Export-Certificate -Cert cert:\localMachine\my\<Thumbprint-of-cert> -FilePath E:\sc9_com_install\storefront.local.cer
    • sc9com_3
  7. download MSBuild Microsoft Visual Studio Web targets (available from Nuget) then extract the Web targets package, copy the \tools\VSToolsPath\Web\Microsoft.Web.XmlTransform.dll file into E:\sc9_com_install
  8. download Sitecore Experience Accelerator 1.7.1 (Note: must log into https://dev.sitecore.net/ before downloading) and put it into E:\sc9_com_install
  9. download Sitecore Powershell Extensions 4.7.2 then put it into E:\sc9_com_install
  10. download and unzip Packages for On Premises 2018.07-2.2.126 (Note: must log into https://dev.sitecore.net/ before downloading)
  11. unzip E:\sc9_com_install\SIF.Sitecore.Commerce.1.2.14.zip and then rename E:\sc9_com_install\SIF.Sitecore.Commerce.1.2.14 to E:\sc9_com_install\SIF for a better practice
  12. unzip the E:\sc9_com_install\Sitecore.BizFX.1.2.19.zip
  13. unzip the E:\sc9_com_install\Sitecore.Commerce.Engine.SDK.2.2.72.zip file then copy the E:\sc9_com_install\Sitecore.Commerce.Engine.SDK.2.2.72\Sitecore.Commerce.Engine.DB.dacpac file into E:\sc9_com_install
    • Note: you will see the following error message if you copy / paste the one of XC 9 Update 1
    • sxc902_5
    • ERROR Message=SQL.InsertEntity.Fail: Id=’Entity-PolicySet-ControllerMethodRolesPolicySet’|Environment=’GlobalEnvironment’|Message=’Procedure or function sp_CommerceEntitiesInsert has too many arguments specified.

  14. unzip E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126.zip
    • open E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126\wwwroot\bootstrap\Global.json
    • replace the Database‘s value to “SitecoreCommerce9_Global” at line 109 (the default value SitecoreCommerce_Global is NOT correct)
    • ensure the Server‘s value is “.” at line 113 (it’s empty by default)
    • sxc902_4.png
    • zip the folder E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126 as E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126\Sitecore.Commerce.Engine.2.2.126.zip file then overwrite E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126.zip with it
  15. download sc9_com_install.ps1 and put it into E:\sc9_com_install\SIF then open it to correct 09 parameters below:
    1. $SitePrefix
    2. $ScInstallDirectory
    3. $SiteHostHeaderName
    4. $SqlServer
    5. $SqlDbPrefix
    6. $CommerceEngineCertificatePath
    7. $SolrUrl
    8. $SolrRoot
    9. $SolrService
  16. (optional): you can specify any local account (note: it will be created automatically if non-existent) to be set up for the various application pools that are created as part of the deployment at line 76-77 of sc9_com_install.ps1
    • sxc902_1
  17. (optional): if you play with SQL Server 2017, you will have to download DeployCommerceDatabase.psm1 then overwrite E:\sc9_com_install\SIF\Modules\DeployCommerceDatabase\DeployCommerceDatabase.psm1
  18. (optional): if you have multiple instances of SQL Server on your machine, you will have to:
    • unzip E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126.zip
    • open E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126\wwwroot\bootstrap\Global.json
    • replace the Server’s value to your SQL Server instance at line 113 (Note: double-backslash escape if any)
    • sxc902_3.png
    • open E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126\wwwroot\data\Environments\PlugIn.Habitat.CommerceAuthoring-1.0.0.json then replace the Server‘s value to your SQL Server instance at line 130 (Note: double-backslash escape if any)
    • open E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126\wwwroot\data\Environments\PlugIn.AdventureWorks.CommerceAuthoring-1.0.0.json then replace the Server‘s value to your SQL Server instance at line 130 (Note: double-backslash escape if any)
    • zip the folder E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126 as E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126\Sitecore.Commerce.Engine.2.2.126.zip file then overwrite E:\sc9_com_install\Sitecore.Commerce.Engine.2.2.126.zip with it
  19. (optional): you may get timeout exceptions (some tasks’ execution timeout is only 12 minutes by default and the remote query timeout of SQL Server is only 10 minutes by default) so I suggest:
    • download SitecoreUtilityTasks.psm1 then overwrite E:\sc9_com_install\SIF\Modules\SitecoreUtilityTasks\SitecoreUtilityTasks.psm1 in order to increase the execution timeout
    • download PerformanceTweak.config then put it into  \sc9com.local\App_Config\Environment in order to turn all Sitecore jobs off and disable xDB for a better installation (you know, it’s a super long operation :D)
    • configure the remote query timeout option of SQL Server:
      1. using SQL Server Management Studio
      2. in Object Explorer, right-click a server and select Properties
      3. under Remote server connections, in the Remote query timeout box, type or select a value from 0 through 2,147,483,647 to set the maximum number seconds for SQL Server to wait before timing out
    • consider to put $global:ProgressPreference = ‘silentlyContinue’ into the sc9_com_install.ps1 in order to speed up the operation
  20. launch PowerShell as an administrator
    • sc9com_6
    • hopefully there is nothing can stop the installation process now
    • sxc902_10.png
  21. open a browser then navigate to storefront.local/, you would see the default page of Sitecore webiste. That’s because we don’t use the default host name sxa.storefront.com so we need to correct it inside Sitecore
    • log into sc9com.local/sitecore/
    • access /sitecore/content/Sitecore/Storefront/Settings/Site Grouping/Storefront
    • update Host Name to storefront.local and then publish it
    • sc9com_8.png
    • refresh storefront.local/, you would see something like this
    • sxc902_8.png
    • I’m sure that you want to make it more fancy so access /sitecore/content/Sitecore/Storefront/Presentation/Page Designs
    • update Theme to Storefont Branded and then publish it
    • sc9com_14
    • refresh storefront.local/, you would see something like this
    • sxc902_9.png
  22. DO NOT forget to perform Post-Installation Steps

The recommendations

  • we can remove the tasks completed from E:\sc9_com_install\SIF\Configuration\Commerce\Master_SingleServer.json and re-do Step 20 if there is something wrong (especially for Note: some known issues below) so that we are able to save a lot of time 😀
  • if there is something wrong during installation process, we always have a chance to correct it via json files (note: need to do IIS reset after updating):
    1. C:\inetpub\wwwroot\SitecoreIdentityServer\wwwroot\appsettings.json
    2. C:\inetpub\wwwroot\CommerceShops_Sc9\wwwroot\bootstrap\Global.json
    3. C:\inetpub\wwwroot\CommerceOps_Sc9\wwwroot\bootstrap\Global.json
    4. C:\inetpub\wwwroot\CommerceMinions_Sc9\wwwroot\bootstrap\Global.json
    5. C:\inetpub\wwwroot\CommerceAuthoring_Sc9\wwwroot\bootstrap\Global.json
    6. C:\inetpub\wwwroot\CommerceShops_Sc9\wwwroot\data\Environments\Plugin.SQL.PolicySet-1.0.0.json
    7. C:\inetpub\wwwroot\CommerceShops_Sc9\wwwroot\data\Environments\PlugIn.Habitat.CommerceAuthoring-1.0.0.json
    8. C:\inetpub\wwwroot\CommerceShops_Sc9\wwwroot\data\Environments\PlugIn.AdventureWorks.CommerceAuthoring-1.0.0.json

How to uninstall it?

  • download sc9_com_uninstall.ps1 and put it into E:\sc9_com_install then open it to correct 07 parameters below:
    1. $EngineSuffix
    2. $Prefix
    3. $SolrService
    4. $PathToSolr
    5. $SqlServer
    6. $SqlAccount
    7. $SqlPassword
  • launch PowerShell as an administrator
    • sc9com_15.png
  • hopefully, it runs well and cleans everything up

Note: some known issues

  1. The service cannot accept control messages at this time
    • sc9com_16.png
    • access IIS, start sc9com.local site and sc9com.local application pool manually (note: you may need to do it several times) if they’re in STOP status, somehow IIS cannot restart those ones after stopping them
  2. The wait operation timed out: [SqlException (0x80131904): Connection Timeout Expired. The timeout period elapsed during the post-login phase. The connection could have timed out while waiting for server to complete the login process and
    respond; Or it could have timed out while attempting to create multiple active connections.

    • sc9com_17.png
    • open E:\sc9_com_install\SIF\Configuration\Commerce\Master_SingleServer.json to remove the tasks completed
    • for instance, I would remove all the completed tasks before InstallSXAFrameworkModule then re-do Step 20 again
    • sc9com_18.png
  3. Request timed out:  Exception Details: System.Web.HttpException: Request timed out.
    • sc9com_19.png
    • my suggestions:
      1. open E:\sc9_com_install\SIF\Configuration\Commerce\Master_SingleServer.json to remove the tasks completed
        • for instance, I would remove all the completed tasks before PublishExtensions then re-do Step 20 again
      2. consider to perform Step 19 as well if solution #1 does not work as expected then re-do Step 20 again
  4. Something went wrong restarting SQL server again: Cannot validate argument on parameter ‘InputObject’. The argument is null or empty. Provide an argument that is not null or empty, and then try the command again.
    • sc9com_22
    • somehow SQL Server window service cannot restart after stopping, ensure SQL Server window service is running
  5. Install-SitecoreConfiguration : Cannot find path ‘C:\inetpub\wwwroot\CommerceOps_Sc9\wwwroot\config.json’ because it does not exist.
    • sc9com_50
    • in Step 15, ensure to create Sitecore.Commerce.Engine.2.2.126.zip correctly (especially directory structure)
  6. Get Token From Sitecore.IdentityServer: HTTP Error 503. The service is unavailable
    • sc9com30.jpg
    • my suggestions:
      1. ensure to install .Net Core stuffs
      2. correct connection string in “C:\inetpub\wwwroot\SitecoreIdentityServer\wwwroot\appsettings.json” and then do IIS reset
      3. correct the application pool of SitecoreIdentityServer site in IIS
  7. Ensure/Sync default content paths for environment AdventureWorksAuthoring failed
    • sxc902_2
    • ensure to perform Step 14 and Step 18 correctly

Got issues?

Please send your issues (with screenshots if possible) to viet.hoang.sitecore@gmail.com so that I have a chance to understand your problem and be able to suggest the solution.

Happy Sitecore Installation!

5 thoughts on “Sitecore Commerce 9 Update 2 and Step-by-step Install Guide on your machine

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.