THIS IS ARCHIVED DOCUMENTATION

Deploying Coveo for Sitecore on the Content Delivery Servers

This is for:

Developer System Administrator

This guide is part of the Coveo for Sitecore Scaling Guide and considers that you have a setup similar to the one in that guide.

If not, read the steps carefully since you’ll need to tailor some of them for your environment.

Step 1: Copying the Package to CDs

The Coveo for Sitecore installation package contains several files that are added to the Sitecore website directory.

  1. Locate the installation package you used for the content manager (see Downloads).

  2. Unzip the Coveo for Sitecore XX <BUILD_NUMBER>.zip.

  3. Open the package.zip file.

  4. Copy the contents of the files folder to the appropriate folders on each CD. The files folder mimics the folder structure found in the Sitecore website.

    • For Sitecore 7 and Sitecore 8 deployments, copy the contents of the files folder into the corresponding folders under Local Disk\inetpub\wwwroot\<SITECORE_INSTANCE>\Website\ on each CD.

    • For Sitecore 9 deployments, copy the contents of the files folder into the corresponding folders under Local Disk\inetpub\wwwroot\<SITECORE_INSTANCE> on each CD.

Copying Coveo for Sitecore SXA files to CDs

If you’re using SXA, copy the Coveo for Sitecore SXA package files to your CDs the same way you did above.

  1. Locate the installation package you used for the content manager (see Downloads).

  2. Unzip the appropriate Coveo for Sitecore SXA <SXA_VERSION(S)> <BUILD_NUMBER>.zip file, based on the version of Sitecore you’re using.

  3. Open the package.zip file.

  4. Copy the contents of the files folder to the appropriate folders on each CD. The files folder mimics the folder structure found in the Sitecore website.

    • For Sitecore 8 deployments, copy the contents of the files folder into the corresponding folders under Local Disk\inetpub\wwwroot\<SITECORE_INSTANCE>\Website\ on each CD.

    • For Sitecore 9 deployments, copy the contents of the files folder into the corresponding folders under Local Disk\inetpub\wwwroot\<SITECORE_INSTANCE> on each CD.

Step 2: Ensuring Access to the Encryption Keys

Coveo for Sitecore (December 2016)

Coveo for Sitecore creates a Coveo directory in the Sitecore instance Data directory to store configuration encryption keys (ConfigurationEncryptionKeys\IndexingEncryptionKeys). These keys must be the same on all the Sitecore instances to be able to decrypt the encrypted configuration elements.

  1. Navigate to Local Disk\inetpub\wwwroot\<SITECORE_INSTANCE>\Data\.
  2. Copy the folder Coveo to each CD server in their Data folder.

Coveo for Sitecore (December 2016) Coveo for Sitecore (May 2019)

The encryption keys are stored in the Properties table of the core database. If your CMs and CDs don’t share the same core database, make sure you have a replication strategy in place.

Coveo for Sitecore (May 2019)

The encryption keys are stored in the Properties table of the core database (for Sitecore versions up to 9.0 inclusively) or the web database (for Sitecore versions 9.1 onwards). These encryption keys must be the same on all the Sitecore instances to be able to decrypt the encrypted configuration elements.

If your CMs and CDs don’t share the same core/web database, make sure you have a database replication strategy in place.

Step 3: Copying the Configuration Files

Since the index is shared between all the Sitecore instances, you need to configure all the additional Sitecore instances to use the same base configuration as the CM1 Sitecore instance:

  1. Delete the additional Sitecore instances App_Config\Include\Coveo folder.

  2. Copy the App_Config\Include\Coveo folder from the CM1 Sitecore instance to all the additional Sitecore instances.

  3. Sitecore 9 Copy the App_Config\Modules\Coveo folder from the CM1 Sitecore instance to all the additional Sitecore instances.

Step 4: Enabling SwitchMasterToWeb

Sitecore 9

Sitecore provides a file named SwitchMasterToWeb.config.example.

  • For Sitecore 7.x, this file must be downloaded from the Sitecore web site (see Sitecore Scaling Guide).
  • For Sitecore 8.0, the file is located in the App_Config\Include folder.
  • For Sitecore 8.1+, the file is located in the App_Config\Include\Z.SwitchMasterToWeb folder.

Coveo provides a SwitchMasterToWeb.Coveo.config.example located in the App_Config\Include\Coveo folder.

Both files should be enabled. To ensure that all indexes are disabled correctly, we recommend that you move SwitchMasterToWeb.config.example and SwitchMasterToWeb.Coveo.config.example to the subfolder named Z.SwitchMasterToWeb. For Sitecore versions prior to 8.1, you should create the folder.

Sitecore first parses .config files in alphabetical order and then processes all subfolders and their content in alphabetical order. Prefixing the subfolder name with Z ensures that the .config files it contains are processed at the very end, and consequently disables search indexes defined in all previously parsed .config files.

  1. Enable the Sitecore SwitchMasterToWeb.config.example file by removing the .example extension.
  2. Enable the Coveo SwitchMasterToWeb.Coveo.config.example file by removing the .example extension.
  3. Open the SwitchMasterToWeb.Coveo.config file and apply the following changes:

    1. You should apply the following patches as only the index definition for the pub database is used, the others have to be removed:

      The CD servers shouldn’t be used to perform indexing tasks. All <strategy> elements must be removed from the <index> definition.

       <indexes>
   <index id="Coveo_master_index">
     <patch:delete />
   </index>
   <index id="Coveo_web_index">
     <patch:delete />
   </index>
   <index id="Coveo_pub_index">
     <strategies>
       <patch:delete />
     </strategies>
   </index>
 </indexes>

    2. In the scenario above, only the pub and core databases are used on the CD servers. By default, Coveo for Sitecore creates sites using the web database, which will cause an error in the current setup. To change the sites, create a <sites> section and patch the references to use the pub database:

       <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
   <sitecore>
     ...
     <sites>
       <site name="coveorest">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
       <site name="coveoanalytics">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
       <site name="coveo_website">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
     </sites>
   </sitecore>
 </configuration>

    3. Remove the sitecore/scheduling element and its SynchronizeTopResults agent, as the web database isn’t used anymore.

  4. Open the Coveo.SearchProvider.Custom.config file located in the App_Config\Include\Coveo folder and apply the following changes:

    1. Coveo for Sitecore (June 2016)

      A Content Delivery server shouldn’t synchronize the top results or clean up the indexes, as it doesn’t index items. The Coveo for Sitecore agents need to be deleted:

      1. Locate the sitecore/scheduling element. It should look like this:

         <scheduling>
   <agent name="CoveoSynchronizeTopResults">
     <DatabasesToSynchronize>master;web;pub</DatabasesToSynchronize>
   </agent>
  </scheduling>

      2. Replace the Top Results agent inner element with <patch:delete />, as such:

         <scheduling>
   <agent name="CoveoSynchronizeTopResults">
     <patch:delete />
   </agent>
 </scheduling>

      3. Also replace the CleanUpAfterRebuildAgent inner element with <patch:delete />, as such:

         <scheduling>
   <agent type="Coveo.CloudPlatformClient.Agents.CleanUpAfterRebuildAgent, Coveo.CloudPlatformClient">
     <patch:delete />
   </agent>
 </scheduling>

    2. Furthermore, we recommend that you skip the Sitecore login validation and credentials update, to simplify the deployment. Add the following section in the defaultIndexConfiguration element:

       <defaultIndexConfiguration>
   ...
   <securityConfiguration type="Coveo.Framework.Configuration.SecurityConfiguration, Coveo.Framework">
     <skipSitecoreCredentialsUpdate>true</skipSitecoreCredentialsUpdate>
     <skipSitecoreLoginCheck>true</skipSitecoreLoginCheck>
   </securityConfiguration>
 </defaultIndexConfiguration>

    3. During the initialization, Coveo for Sitecore accesses CES to validate it has been properly initialized. This step isn’t necessary on Content Delivery servers, and should be skipped. Add the following element in the defaultIndexConfiguration section:

       <defaultIndexConfiguration>
   ...
   <skipFirstTimeSetupCheck>true</skipFirstTimeSetupCheck>
 </defaultIndexConfiguration>
  5. Save and close the files.

  1. Enable the Sitecore SwitchMasterToWeb.config.example file by removing the .example extension.

  2. Enable the Coveo SwitchMasterToWeb.Coveo.config.example file by removing the .example extension.

  3. In the Coveo for Sitecore Scaling Guide, a new Pub database was created. You should apply the following patches only if you use a different database than web for your CD servers.

    1. Open the SwitchMasterToWeb.Coveo.config file and apply the following changes:

      The CD servers shouldn’t be used to perform indexing tasks. All <strategy> elements must be removed from the <index> definition.

       <indexes>
   <index id="Coveo_master_index">
     <patch:delete />
   </index>
   <index id="Coveo_web_index">
     <patch:delete />
   </index>
   <index id="Coveo_pub_index">
     <strategies>
       <patch:delete />
     </strategies>
   </index>
 </indexes>

    2. By default, Coveo for Sitecore creates sites using the web database, which will cause an error in the current setup. To change the sites, create a <sites> section and patch the references to use the pub database:

       <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
   <sitecore>
     ...
     <sites>
       <site name="coveorest">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
       <site name="coveoanalytics">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
       <site name="coveo_website">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
       <site name="website">
         <patch:attribute name="database">pub</patch:attribute>
       </site>
     </sites>
   </sitecore>
 </configuration>

  4. Open the Coveo.SearchProvider.Custom.config file located under the App_Config\Include\Coveo folder, and apply the following changes:

    1. Coveo for Sitecore (June 2016)

      A CD shouldn’t clean up the indexes as it doesn’t index items. The CleanUpAfterRebuildAgent agent needs to be deleted:

      1. Locate the CleanUpAfterRebuildAgent agent element. It should look like this:

         <agent type="Coveo.CloudPlatformClient.Agents.CleanUpAfterRebuildAgent, Coveo.CloudPlatformClient">
   <indexesToCleanUp>Coveo_master_index;Coveo_web_index;Coveo_pub_index</indexesToCleanUp>
 </agent>

      2. Replace the whole element with the following one to patch delete the agent:

         <agent type="Coveo.CloudPlatformClient.Agents.CleanUpAfterRebuildAgent, Coveo.CloudPlatformClient">
   <patch:delete />
 </agent>

    2. Furthermore, we recommend that you skip the Sitecore login validation and credentials update, to simplify the deployment. Add the following section in the defaultIndexConfiguration element:

       <defaultIndexConfiguration>
   ...
   <securityConfiguration type="Coveo.Framework.Configuration.SecurityConfiguration, Coveo.Framework">
     <skipSitecoreCredentialsUpdate>true</skipSitecoreCredentialsUpdate>
     <skipSitecoreLoginCheck>true</skipSitecoreLoginCheck>
   </securityConfiguration>
 </defaultIndexConfiguration>

  5. Save and close the files.

What’s Next?

You’re now done with deploying Coveo for Sitecore, and you should test your connection to make sure everything is working (see Validating Connectivity of the New Hosts).