Coveo for Sitecore 5 is now available!

Prepare the Sitecore Content Manager for a Scaled Environment

Once you correctly built the whole Sitecore infrastructure, you may proceed to configure Coveo for Sitecore on your main Content Manager (CM1).

Step 1: Configuring the pub Database Search Index

In the Sitecore Scaling Guide, a database named pub was added to Sitecore. Although adding a database isn’t mandatory, it’s highly recommended by Sitecore.

To index a new database, you must add a new index definition.

  1. On CM1, in the App_Config\Include\Coveo folder of your Sitecore instance, open the Coveo.SearchProvider.Custom.config file.
  2. Inside of your sitecorenode, create a contentSearch/configuration/indexes element with a hint attribute like this:

     <sitecore>
       <contentSearch>
         <configuration>
           <indexes hint="list:AddIndex">
           </indexes>
         </configuration>
       </contentSearch>
     </sitecore>
    
  3. On CM1, open the Coveo.SearchProvider.config file located in the App_Config\Include\Coveo folder for Sitecore 7 and 8 sites or in the App_Config\Modules\Coveo folder for Sitecore 9 sites.
  4. Find the index element that corresponds to the web database. The element should look like this:

     <index id="Coveo_web_index" type="Coveo.SearchProvider.ProviderIndex, Coveo.SearchProvider" patch:before = "*[2]">
     ...
     </index>
    
  5. Select and copy the whole element, from <index...> to </index>.
  6. In theCoveo.SearchProvider.Custom.config file, paste it before the </indexes> element.

    You shouldn’t modify theCoveo.SearchProvider.config file directly, as it may cause unexpected upgrade issues and loss of configuration.

  7. Apply the following changes to the element that you have just pasted.
    1. Change the value of the id attribute to Coveo_pub_index. The element should now look like this:

       <index id="Coveo_pub_index" type="Coveo.SearchProvider.ProviderIndex, Coveo.SearchProvider" patch:before = "*[2]">
      
    2. Increment the number in the patch:before attribute value. The element should now look like this:

       <index id="Coveo_pub_index" type="Coveo.SearchProvider.ProviderIndex, Coveo.SearchProvider" patch:before = "*[3]">
      
    3. Set all the index/locations/crawler/database elements value to pub. There should be at least two elements to update. The elements should now look like this:

       <database>pub</database>
      
    4. Replace the <strategy ref="contentSearch/indexUpdateStrategies/onPublishEndAsync"/> node with the following nodes:

       <strategy name="OnPublishEndAsyncPub" type="Sitecore.ContentSearch.Maintenance.Strategies.OnPublishEndAsynchronousStrategy, Sitecore.ContentSearch" >
         <param desc="database">pub</param>
         <!--
           Whether a full index rebuild should be triggered when the number of items in the EventQueue exceeds the number specified
           in ContentSearch.FullRebuildItemCountThreshold.
         -->
         <CheckForThreshold>true</CheckForThreshold>
       </strategy>
      
    5. For Sitecore 9 deployments only, you need to ensure this <strategy> element is disabled on CD servers by applying the following rule based patch.

      1. Select and copy the whole element, from <strategy...> to </strategy>.
      2. Paste the copy immediately below the original <strategy> element.
      3. Edit the second <strategy> element to obtain the following result:

        <strategy name="OnPublishEndAsyncPub" type="Sitecore.ContentSearch.Maintenance.Strategies.OnPublishEndAsynchronousStrategy, Sitecore.ContentSearch">
          <param desc="database">pub</param>
          <!--
          Whether a full index rebuild should be triggered when the number of items in the EventQueue exceeds the number specified
          in ContentSearch.FullRebuildItemCountThreshold.
          -->
          <CheckForThreshold>true</CheckForThreshold>
        </strategy>
        <strategy role:require="ContentDelivery" name="OnPublishEndAsyncPub" type="Sitecore.ContentSearch.Maintenance.Strategies.ManualStrategy, Sitecore.ContentSearch">
          <param desc="database">
            <patch:delete />
          </param>
          <!--
          Whether a full index rebuild should be triggered when the number of items in the EventQueue exceeds the number specified
          in ContentSearch.FullRebuildItemCountThreshold.
          -->
          <CheckForThreshold>
             <patch:delete />
          </CheckForThreshold>
        </strategy>
        
  8. In your sitecore node, add the following element. This synchronizes the Top Results from your pub database.

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

    Coveo for Sitecore (June 2016)

    Execute this step only for the April 2016 release (4.0.171). Skip this step for June 2016 and later releases (4.0.222+).

    Now that you have the pub index, the Coveo for Sitecore agents need to be updated.

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

       <scheduling>
         <agent name="CoveoSynchronizeTopResults">
           <patch:delete />
         </agent>
       </scheduling>
      
    2. Add a section for the CleanUpAfterRebuildAgent agent to specify to clean up the pub index as well:

       <scheduling>
         <agent name="CoveoSynchronizeTopResults">
           <patch:delete />
         </agent>
         <agent type="Coveo.CloudPlatformClient.Agents.CleanUpAfterRebuildAgent, Coveo.CloudPlatformClient">
           <indexesToCleanUp>Coveo_master_index;Coveo_web_index;Coveo_pub_index</indexesToCleanUp>
         </agent>
       </scheduling>
      
  9. Save and close the files.

Step 2: Rebuilding the Search Index for the pub Database

The pub database is now properly configured and can be indexed by Coveo for Sitecore. Follow these steps to index its content:

  1. Log into the Sitecore Desktop.
  2. Access the Indexing Manager (Sitecore Start Menu > Control Panel > Indexing > Indexing Manager).
  3. Select the Coveo_pub_index index and choose Rebuild. Depending on the number of Sitecore items to index, this task may take several minutes to complete.
  4. Choose Finish when the indexing is completed. The content of the pub database is now indexed.

Your Sitecore items are indexed with clickable URI values matching a hostName value assigned to your Content Management instance. However, the clickable URI is also computed whenever a Coveo-powered search interface receives search results from the index to ensure that the intended Content Delivery instance is hit whenever a website visitor clicks on a search result.

Step 3: Configuring the Server URL on the Instance to Be Scaled

Coveo for Sitecore (October 2016)

As of the October 2016 release of Coveo for Sitecore, you don’t need to configure the server URL, as the Expanded Security Provider handles the securities for you (see Upgrading to the Expanded Security Provider).

When scaling Sitecore instances, you need to ensure that the <serverUrl> element value is the same on all the instances and is set to the public URL of the Sitecore instances farm. In general, it should be the public URL of the content management instances network load balancer (NLB). The server URL is used by the on-premises Sitecore Security Provider to call the Sitecore instances. It also affects the clickable URI of the indexed and queried Sitecore items.

Follow these steps to configure the CM1 instance:

  1. Open your Coveo.SearchProvider.Custom.config file.
  2. Inside coveo/defaultIndexConfiguration, add a node called serverUrl.
  3. Set the public URL of the Sitecore farm in plain text in the node. Remember to add the URL scheme (http or https).

     <defaultIndexConfiguration>
       ...
       <serverUrl>http://PublicSitecoreFarmUrl/</serverUrl>
     </defaultIndexConfiguration>
    
  4. Save and close the file. Your server URL is now set.

Step 4: Configuring the UseHostHeaderForRequestURL Setting

Under the hood, Coveo for Sitecore performs HTTP requests on its own. To ensure that these internal HTTP requests are targeting the expected endpoint, the aspnet:UseHostHeaderForRequestUrl setting must be set properly (see ASP.NET appSettings Element for details).

The aspnet:UseHostHeaderForRequestUrl setting must be set to true when the Sitecore instance is deployed behind a network load balancer (NLB). Omitting this setting may cause URL-resolving issues.

Follow these steps to configure the setting on the CM1 instance:

  1. Open your web.config file.
  2. Inside configuration / appSettings, add the following element:

     <add key="aspnet:UseHostHeaderForRequestUrl" value="true" />
    
  3. Save and close the file.

Step 5: Configuring the Farm Name on the Instance to Be Scaled

When scaling Sitecore instances, you need to set a farm name to ensure all the Sitecore instances share the same resources. Setting a farm name affects the names of the sources, field sets, security provider, and user identities. Instead of assigning them an individual name, you give them the same label. Follow the Assigning a Farm Name to Coveo for Sitecore Resources guide to configure the CM1 instance.

When choosing a Farm Name different from the CM1 host name, you must rebuild your Coveo indexes (see Coveo for Sitecore Indexing Guide). Some resources, like the sources, need to be rebuilt to apply the name change. Skipping the rebuild would cause naming inconsistencies that would prevent queries and components from reaching the right resources.

What’s Next?

Now that you installed Coveo for Sitecore on your first Content Manager, you may proceed either to:

What's Next for Me?