THIS IS ARCHIVED DOCUMENTATION

Installing Coveo for Sitecore

This page covers the installation of Coveo for Sitecore On-Premises into your Sitecore instance.

This page covers the installation of Coveo for Sitecore Cloud into your Sitecore instance.

Prerequisites

Installation Procedure

  1. Install Coveo Enterprise Search (CES) On-Premises

  2. Install the Coveo for Sitecore package using the Sitecore Installation Wizard ( Sitecore Desktop > Start Menu > Development Tools > Installation Wizard).

    This operation can take several minutes to complete. If you’re asked whether to overwrite files or items during the installation, click Yes to all.

  3. Once the package is installed, the Coveo for Sitecore Configuration Wizard will appear.

  4. From the Welcome screen, you can access useful documentation about the installation process. When you’re ready to proceed, click Next.

  5. In the Connect to Coveo Cloud screen:

    1. Click Sign-Up or Log Into Coveo Cloud.

    2. On the Log into Coveo Cloud page, choose your authentication provider and enter your credentials.

    3. On the Grant Privileges page, click Authorize.

  6. In the Coveo Cloud Organization screen:

    1. If you don’t have access to a Coveo organization, you will be given the opportunity to create one.

      If you have bought a Coveo for Sitecore Pro or Enterprise edition subscription, you should already have access to an organization with those rights, and should follow step 6.b instead.

      1. In New organization name, enter the name of your new organization.

      2. In Select your license plan, select On-Premises Free Edition.

      3. Click Next.

    2. If you already have access to a Coveo organization, you should be able to select an existing organization:

      1. Select your organization.

      2. Click Next.

    3. If you already have access to a Coveo organization, but would like to create a new organization:

      1. In the dropdown menu, select Create new organization.
      2. In New organization name, enter the name of your new organization.
      3. In Select your license plan, select On-Premises Free Edition.
      4. Click Next.

  7. In the Configure where the Coveo index is located screen:

    1. Choose either one of these options:

      1. If you will be running CES and Sitecore locally, on the same server, choose On the same server as this Sitecore instance.

      2. If you will be running CES remotely, on a separate server, choose On a remote server.

    2. In Coveo Index Path, enter the path of the index folder on the CES server (typically C:\CES7).

      • If you have not already performed the First-Time Setup in CES, specify a path of your choice (for example, D:\CES7). The required index folder will be created where you specified on the CES server, and the Coveo.SearchProvider.config.example file will be updated to reflect this location. If you have already performed the First-Time Setup, specify the path of the index folder created by CES (the default location is C:\CES7).
      • Make sure that you enter a path with a valid format. You shouldn’t use a network or DFS path.
  8. In the Configure the REST endpoint screen:

    In Search API URI, enter:

    1. For a local setup: http://localhost:8080/

    2. For a remote setup: http://{CES server's FQDN or alias}:8080/

      The port is 8080 by default but can be changed. See Changing the REST Search API Default Port.

  9. In Application Secret, enter the application secret of the Coveo Search API (located in the applications/secret node of the config.yml file).

    The Application Secret isn’t the same thing as the Secret Token created during CES setup. Entering an incorrect application secret will result in a 403 - Permission Denied error.

  10. Click Next.

  11. In the Configure the RabbitMQ indexing queue connection screen:

    1. In URI, enter:

      1. For a local setup: amqp://localhost:5682/

      2. For a remote setup: amqp://{CES server's FQDN or alias}:5682/

    2. In Username, enter the username of a RabbitMQ administrator account (the default value is guest).

    3. In Password, enter the password of the account (the default value is guest).

      If you set up your own RabbitMQ administrator credentials while installing CES (see Installing Coveo Enterprise Search (CES) On-Premises), you must specify those credentials here.

      The password entered on this screen is encrypted and saved in the Coveo.SearchProvider.Custom.config.example file.

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

      An encryption key is automatically created in the core database of your Sitecore instance.

      Coveo for Sitecore (May 2019)

      An encryption key is automatically created in the core database (for Sitecore versions up to 9.0 inclusively) or the web database (for Sitecore versions 9.1 onwards) of your Sitecore instance.

  12. Click Next.

  13. In the Configure the Coveo Admin Service screen:

    In Admin Service URI, enter:

    • For a local setup: http://localhost/AdminService, OR

    • For a remote setup (unsecured): http://{CES server's FQDN or alias}/AdminService, OR

    • For a remote setup (secured): https://{CES server's FQDN or alias}/AdminService

  14. In case you want to secure the Admin Service:

    1. Select Use a secure Admin Service.

    2. In Admin Service Username, enter the username that you configured in CES to secure the Admin Service.

    3. In Admin Service Password, enter the password that you configured in CES to secure the Admin Service.

      The admin service password entered on this screen is encrypted and saved in the Coveo.SearchProvider.Custom.config.example file.

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

      An encryption key is automatically created in the core database of your Sitecore instance.

      Coveo for Sitecore (May 2019)

      An encryption key is automatically created in the core database (for Sitecore versions up to 9.0 inclusively) or the web database (for Sitecore versions 9.1 onwards) of your Sitecore instance.

    4. In Certificate File, choose the certificate file ( .pfx) that was previously generated and exported by the CES installation wizard.

    5. In Private Key Password, enter the certificate’s private key password that you configured previously in the CES installation wizard.

    6. In Administrator Username, enter the username of an account that’s a member of the Local Administrators group on the Sitecore server.

    7. In Administrator Password, enter the password of the account.

  15. Click Next.

  16. In the Configure the Sitecore credentials used to retrieve security permissions screen:

    1. In Username, enter the username of the Sitecore account to use to retrieve security permissions of indexed items.

    2. In Password, enter the password of the Sitecore account to use to retrieve security permissions of indexed items.

      Create a dedicated Sitecore admin user for Coveo and use it in the activation steps. Assigning a dedicated user to Coveo for Sitecore will prevent lock-down issues.

      The password entered on this screen is encrypted and saved in the Coveo.SearchProvider.Custom.config.example file.

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

      An encryption key is automatically created in the core database of your Sitecore instance.

      Coveo for Sitecore (May 2019)

      An encryption key is automatically created in the core database (for Sitecore versions up to 9.0 inclusively) or the web database (for Sitecore versions 9.1 onwards) of your Sitecore instance.

  17. Click Next.

  18. In the Configure Body indexing options screen, s elect the type of body indexing that you prefer for your Sitecore items.

    1. To index only Sitecore item data, select Only index Sitecore item data.

    2. To index the full HTML rendering of the published Sitecore items, choose Index rendered HTML.

    3. In the Configure Body indexing options screen:

    4. If you don’t need to index permissions, select Disable Security Permissions on Documents, and click Next.

  19. To activate Coveo for Sitecore, in the Activate Coveo for Sitecore screen:

    1. Check Automatically rename the files.

    2. Click Next.

    3. Click Close, and after a few moments you should see the last screen of the Configuration Wizard. This screen contains links to useful documentation to finalize your Coveo for Sitecore installation.

  20. Depending on your Sitecore revision, there may be some lines that you want to uncomment in the Coveo.SearchProvider.config file. Scan the file for any relevant section. For example, you may want to uncomment the fields/field[@fieldName="culture"] node if you’re using a Sitecore revision later than 150400.

    If you installed CES on a remote server, you need to perform additional steps (see Setting Up Coveo for Sitecore in a Remote Server Configuration - On-Premises).

  21. Click Close in the Configuration Wizard.

  22. Once the Configuration Wizard is closed, make sure that you restart both the Sitecore client and server.

    When the Search API is installed on a different machine from CES, you should configure the Search API service manually (for the available options, see Windows Service Configuration File).

  23. On the server where the Search API service is running, open the config.yml file (typically located under C:\Program Files\Coveo Search API 8).

    When editing the config.yml file, make sure that you indent settings using spaces only. Tabs are considered invalid and will therefore prevent the configuration from loading properly.

    After having saved your config.yml file, you must restart your Coveo Search API service for your modifications to take effect.

    1. Ensure that the serverCertificatePath setting points to a valid certificate path. The path should be <CES_INDEX_PATH>\Config\Certificates\cert-ca.pem.

    2. Ensure that the clientCertificatePath setting points to a valid certificate path. The path should be <CES_INDEX_PATH>\Config\Certificates\cert-iis.p12.

  24. Start the Coveo Search API service.

    You can access the services list from Control Panel > System and Security > Administrative Tools > Services.

If you’re using the web database, publish the master database, as items created by Coveo for Sitecore will need to be replicated to this database as well.

  1. Install the Coveo for Sitecore package using the Sitecore Installation Wizard ( Sitecore Desktop > Start Menu > Development Tools > Installation Wizard).

    This operation can take several minutes to complete.

    If you’re asked whether to overwrite files or items during the installation, proceed to do so.

  2. Once the package is installed, the Coveo for Sitecore Configuration Wizard will appear.

  3. From the Welcome screen, you can access useful documentation about the installation process. When you’re ready to proceed, click Next.

  4. In the Log into or Create you Cloud Organization window:

    1. Click Sign-Up or Log Into Coveo Cloud.

    2. Follow the instructions to authorize your Sitecore instance to interact with Coveo.

  5. In the Coveo Cloud Organization screen:

    1. If you don’t have access to a Coveo organization, you will be given the opportunity to create one.

      1. In New organization name, enter the name of your new organization.

      2. In Select your license plan, select Cloud Edition Trial.

      3. Click Next.

    2. If you already have access to a Coveo organization, you should be able to select an existing organization:

      1. Select your organization.

      2. Click Next.

    3. If you already have access to a Coveo organization, but would like to create a new organization:

      1. In the dropdown menu, select Create new organization.

      2. In New organization name, enter the name of your new organization.

      3. In Select your license plan, select Cloud Edition Trial.

      4. Click Next.

  6. In the Configure the Sitecore credentials used to retrieve security permissions screen:

    1. In Username, enter the username of the Sitecore account to use to retrieve security permissions of indexed items.

    2. In Password, enter the password of the Sitecore account to use to retrieve security permissions of indexed items.

      Create a dedicated Sitecore admin user for Coveo and use it in the activation steps. Assigning a dedicated user to Coveo for Sitecore will prevent lock-down issues.

      The password entered on this screen is encrypted and saved in the Coveo.SearchProvider.Custom.config.example file.

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

      An encryption key is automatically created in the core database of your Sitecore instance.

      Coveo for Sitecore (May 2019)

      An encryption key is automatically created in the core database (for Sitecore versions up to 9.0 inclusively) or the web database (for Sitecore versions 9.1 onwards) of your Sitecore instance.

    3. Click Next.

  7. In the Configure Body indexing options screen, select the type of body indexing that you prefer for your Sitecore items.

    1. To index only Sitecore item data, select Only index Sitecore item data.

    2. To index the full HTML rendering of the published Sitecore items, choose Index rendered HTML, and click Next.

  8. In the Configure Body indexing options screen, if you don’t need to index permissions, select Disable Security Permissions on Documents, and click Next.

  9. In the Activate Coveo for Sitecore screen:

    1. Select Automatically rename the files.

    2. Click Next.

  10. If all has gone well, you should see the following screen:

    Click Close.

    The installator may seem to hang for a while at this point. It’s actually performing various tasks and renaming the configuration files in the background.

  11. If you didn’t activate Coveo for Sitecore in the install wizard, on the Sitecore server, remember to rename the following files (located under App_Config\Include\Coveo):

    1. Coveo.CloudPlatformClient.Custom.config.example to Coveo.CloudPlatformClient.Custom.config.

    2. Coveo.SearchProvider.config.example to Coveo.SearchProvider.config.

    3. Coveo.SearchProvider.Custom.config.example to Coveo.SearchProvider.Custom.config.

    4. Coveo.SearchProvider.Rest.config.example to Coveo.SearchProvider.Rest.config.

    5. Coveo.SearchProvider.Rest.Custom.config.example to Coveo.SearchProvider.Rest.Custom.config.

    6. Coveo.UI.Controls.config.example to Coveo.UI.Controls.config.

    7. Coveo.UI.Components.ExperienceEditor.config.example to Coveo.UI.Components.ExperienceEditor.config.

  12. Depending on your Sitecore revision, there may be some lines that you want to uncomment in the Coveo.SearchProvider.Custom.config file. Scan the file for any relevant section. For example, you may want to uncomment the fields/field[@fieldName="culture"] node if you’re using a Sitecore revision later than 150400.

    It’s important that you only modify the .Custom.config files. Modifying the .config files may lead to unexpected bugs during updates.

  13. For Sitecore 9 instances only, changes to your Web.config file are required to ensure that requests targeting the REST endpoint can handle special characters (see Ajax Error 500 When Using Special Characters in a Query - Workaround).

  14. Once the Configuration Wizard has closed, make sure that you restart the Sitecore client.

  15. If you’re using the web database, publish the master database, as items created by Coveo for Sitecore will need to be replicated to this database as well.

What’s Next?

The organization will take a few minutes to finish provisioning (see Understanding Organization Provisioning).

When installing Coveo for Sitecore in a Sitecore configuration with several Content Management ( CM) and/or Content Delivery (CD) hosts, see the Coveo for Sitecore Scaling Guide.

Otherwise you can return to the Coveo for Sitecore Deployment Guide.