Understanding the Search API Configuration File (config.yml)

THIS IS ARCHIVED DOCUMENTATION

Understanding the Search API Configuration File (config.yml)

This is for:

On-Premises only

When loading a search page in a web browser, the JavaScript Search Framework components use the Coveo Search REST endpoint to perform queries. This REST endpoint is installed on the Sitecore website. This way, it can better leverage the information present in the Sitecore context. To make this communication work, the Coveo Search REST endpoint relies on two very important components. The first one is a custom HTTP handler that’s seen as the REST endpoint itself. Its default location on the website is /coveo/rest. The second component is the Search API service, which is usually installed along with the Coveo Enterprise Search (CES) instance. The Search API service is responsible for querying the search index.

The Search API service configuration is located in the config.yml file. This file uses the YAML format.

A YAML file must respect these rules:

The settings are indented using spaces only. Many YAML parsers don’t support tabs. If you want to use the tab character when editing files, make sure that your text editor automatically replaces tabs with spaces.
Comments begin with the hash (#) symbol.
Settings are defined using this key/value format: key: value Notice the space character after the colon (:).
Boolean values are represented with true and false.

The code below shows a sample config.yml file with explanations for the most commonly used settings. For all the available options, see Windows Service Configuration File.

When updating the config.yml file, you must restart the Search API service to use the updated settings.

# The "http" section defines settings used with web browsers requests.
http:
 
  # The "port" setting defines on which port the Search API service is listening.
  # The default port number is (8080).
  port: 8080
 
# The "server" section defines settings used to connect to the Coveo index.
server:
 
  # The "uri" setting defines the host name and port number of the CES instance.
  # Usually the Search API service is installed on the same server as CES.
  uri: https://localhost:52810
 
  # The "serverCertificatePath" setting defines the path of the server certificate file.
  # Using this certificate file, the Search API can validate that it's connecting to the CES instance it's supposed to.
  serverCertificatePath: C:\CES7\Config\Certificates\cert-ca.pem
  
  # The "clientCertificatePath" setting defines the path of the client certificate file.
  # Using this certificate file, CES can validate that the Search API client can be trusted.
  clientCertificatePath: C:\CES7\Config\Certificates\cert-iis.p12
 
# The "applications" section defines settings for a list of different applications.
# The dash (-) symbol represents a list item.
applications:
 
    # The "name" setting defines the application name.
    # It's strongly recommended to use a meaningful name such as the Sitecore instance name.
  - name: Sample Application
 
    # The "secret" setting defines a key that's shared by the Search API and the Sitecore instance to establish a trusted connection.
    # This information must not be available publicly otherwise it can compromise the indexed documents.
    secret: replace this with your own application secret
 
    # The "allowImpersonate" setting defines if the application can impersonate user identities.
    # With Coveo for Sitecore, the value of this setting must be (true) so search queries can be performed
    # with the user that was authenticated by Sitecore.
    allowImpersonate: true
 
# The remaining sections are mostly used when using the Search API in the "standalone" mode.
# They may be used with Coveo for Sitecore for some specific scenarios such as when a user
# is authenticated by Sitecore and Windows at the same time.
basicAuthentication:
  enabled: false
  provider: Active Directory
windowsAuthentication:
  enabled: true
  provider: Active Directory
guest:
  enabled: false
  name: DOMAIN\user
  provider: Active Directory
tokens:
  sharedKey: replace this with your own secret shared key