Installing Sitecore Commerce 8.2.1 – Part 3

  

In the last post, we covered the site initialization process. In this post we will go over the installation of the Commerce Engine.

The Commerce Engine is a .NET Core web service that provides access to the newly rewritten Commerce components. In the release package for Sitecore Commerce, there is a zip package for the Commerce SDK. This contains a Commerce Engine sample solution. Most of the Commerce Engine components are released only as NuGet packages. You will need a solution like this to compose dependencies and configure the application. This solution can also contain additional custom plugins for the Commerce Engine. Since most implementations will have a custom Commerce Engine, the solution in the SDK seems almost like just another piece of the reference storefront.

Create an IIS site

  1. In IIS, create a new website bound to port 5000. Sitecore’s instructions say to name this site CommerceAuthoring, but that seems confusing to me because it implies that it only supports CM. That may be the case here, but eventually you will have Commerce Engine services supporting CD servers as well. I prefer the name CommerceEngine.
  2. IIS will create a new application pool for your site. Adjust the following settings.
    • Select No Managed Code for the CLR version
    • Select Integrated for the pipeline mode
    • Set it to run as the runtime user created in part 1 or create a new user just for this application.
  3. Ensure that the user that the app pool runs under has modify permission to the website folder.

Commerce Engine Configuration Changes

The following configuration changes can be made either before or after compiling the Commerce Engine. You may even consider adding build steps to on your build server to swap out configuration files for different environments. All of these settings are in the .json files in /wwwroot/data/Environments or in /wwwroot/bootstrap/Global.json

  1. If your Commerce Engine is on a separate server than your CSServices, change host for the catalog service URL. The default is http://localhost:1004/CFSolutionStorefrontSite_CatalogWebService/CatalogWebService.asmx.
  2. Change the Sitecore connection settings for all SitecoreConnectionPolicy elements. If the commerce engine is on a separate server, change the Host setting. For any instance, change the UserName and Password settings. You do not need to use an admin user as long as it has access to the /sitecore/content/Commerce node.
  3. Change the database connection settings for all EntityStoreSqlPolicy elements. Typically you will stick with a trusted connection so you only need to update the Server setting.
  4. Configure a payment gateway. If you use Braintree, you only need to update the Merchant ID, Public Key and Private Key settings.  If you use a different gateway, you will need to implement a new plugin for it and swap out the braintree policy with your own.

Create the Databases

  1. Open SSMS and log into the DB server with a sysadmin user.
  2. Open the script CommerceServicesDbScript.sql found in the Commerce Engine SDK folder.
  3. Search for the text SET @userName and set the value to your runtime user name (e.g. DOMAIN\RuntimeUser). Do this for both instances in the file. (Should be approximately lines 510 and 1043)
  4.  Run the script

Compile the Commerce Engine

The compilation steps do not need to be completed on the web server. You can compile the engine on a developer machine and then copy the output files to one or more servers.  Better yet you could set these steps up on a build server so you can automatically deploy changes as you adjust the configuration or develop custom plugins.

  1. Be sure you have installed the .NET Core SDK version that is specified in the Global.json file
  2. Open a command prompt in the directory where you have extracted the Commerce Engine SDK
  3. Restore NuGet packages by running dotnet restore
  4. Publish the files to a local or network folder by running dotnet publish .\Sitecore.Commerce.Engine -o c:\Deploy\Sitecore.Commerce You can change the output directory as you see fit.
  5. Copy the output files to the Commerce Engine website folder on the web server
  6. Confirm the Commerce Engine is running by going to http://localhost:5000/api/$metadata in a browser. Adjust the host as necessary if you are connecting from a remote computer.

Sitecore Configuration Changes

In the \Website\App_Config\Include\Y.Commerce.Engine\Sitecore.Commere.Engine.config in your Sitecore instance, change the service URLs so that it can connect to the Commerce Engine. By default they will use localhost. If Commerce Engine is on a separate server, update accordingly. You should be able to hit the metadata URL from the Sitecore web server.

Bootstrap and Initialize

The following steps are written for using a browser on the web server. Adjust the host as necessary if you are connecting from a remote computer. Alternatively, you can use Postman by importing the Postman folder from the Commerce SDK

  1. Bootstrap the environment by making a request to http://localhost:5000/commerceops/Bootstrap()
  2. Initialize the environments by making requests to:
    • http://localhost:5000/commerceops/InitializeEnvironment(environment=’AdventureWorksShops’)
    • http://localhost:5000/commerceops/InitializeEnvironment(environment=’HabitatAuthoring’)
    • http://localhost:5000/commerceops/InitializeEnvironment(environment=’HabitatMinions’)
    • For a Commerce Engine environment: http://localhost:5000/commerceops/InitializeEnvironment(environment=’MyEnvironment’)

Check log files for any errors. If you get errors about a currency set not being found, this may mean that the Commerce Engine cannot connect to Sitecore. Check the URL and credential settings as well as the user’s access rights.