For on-premises deployments, you can administer and manage your own external Elasticsearch cluster for Pega Platform™. By using an external Elasticsearch cluster, you can scale search independently of the Pega Platform cluster, which provides higher availability and scalability than embedded search. If you use this configuration, you must configure Elasticsearch in client-server mode.

Beginning with with Pega Platform 8.1, you must use Elasticsearch 5.6.9. No other versions of Elasticsearch are supported.

The following high-level tasks are required to configure client-server node:

1. Install and verify that Elasticsearch is working
2. Install Pega plug-ins
3. Configure Pega nodes with Elasticsearch connection details

Install and verify that Elasticsearch is working

1. Download the .zip file for Elasticsearch 5.6.9 from the Elasticsearch website.
2. Extract the .zip file to any directory.
3. From a command prompt, navigate to the elasticsearch-5.6.9/config directory.
4. In the elasticsearch.yml file, update the host IP address and port for Elasticsearch. The default is localhost.
   • network.host: <ESHost_IP>
   • http.port: <port>
5. From a command prompt, navigate to the elasticsearch-5.6.9/bin directory.
6. Run the following command to start the Elasticsearch node:
   • On Microsoft Windows: elasticsearch.bat
   • On Linux: ./elasticsearch
7. Verify that the Elasticsearch server is running by opening a browser or REST client and entering the Elasticsearch server's host name and port in the format: http://<hostname>:<port>/, for example, http://localhost:9200/. A response similar to the following example is displayed if the server is running:

   {
       "name": "OmM3nhT",
       "cluster_name": "elasticsearch",
       "cluster_uuid": "zC0d8NoDTVWSx5j6FzuqUw",
       "version": {
           "number": "5.6.9",
           "build_hash": "877a590",
           "build_date": "2018-04-12T16:25:14.838Z",
           "build_snapshot": false,
           "lucene_version": "6.6.1"
       },
       "tagline": "for search"
   }
   

Install Pega plug-ins

You must install the esplugin-pegaanalyzer and esplugin-custom-index plug-ins that are included in the Pega Platform distribution image at <DistributionImage_Directory>\Additional_Products\PegaESPlugins.

1. Stop the Elasticsearch server before you install the Pega plug-ins.
2. Copy the plug-ins to a directory that is outside of the extracted Elasticsearch 5.6.9 folder. Do not extract the plug-ins.
3. In the elasticsearch-5.6.9/config/elasticsearch.yml file, uncomment the bootstrap.memory_lock:true line.
4. From a command prompt, navigate to the elasticsearch-5.6.9/bin directory.
5. Run the following commands:
   1. To install the analyzer plug-in:
      • On Microsoft Windows: elasticsearch-plugin install "file:///<full_path_of_the_pegaanalyzer_zip>", for example, elasticsearch-plugin install "file:///C:/esplugin-pegaanalyzer-5.6.9.2.zip"
      • On Linux: sudo bin/elasticsearch-plugin install file:///<absolute_path_of_the_pegaanyzer_zip>, for example, sudo bin/elasticsearch-plugin install file:///home/vagrant/Downloads/elasticsearch-5.6.9/esplugin-pegaanalyzer-5.6.9.2.zip
   2. To install the custom index:
      • On Microsoft Windows: elasticsearch-plugin install "file:///<full_path_of_the_custom_index_plugin_zip>"
      • On Linux: sudo bin/elasticsearch-plugin install file:///<absolute_path_of_the_custom_index_plugin_zip>
   3. Start the Elasticsearch node: elasticsearch.bat
6. Verify that the Elasticsearch server is running by repeating step 5 in the previous section.

Configure Pega nodes with Elasticsearch connection details

You can configure connection details either by using a Dynamic System setting (DSS) or by modifying the prconfig.xml file.

To use a Dynamic System Setting:

1. In Dev Studio, click Create > SysAdmin > Dynamic System Settings.
2. In the Short description field, enter a meaningful description for the setting.
3. In the Owning Ruleset field, enter Pega-Engine.
4. In the Setting Purpose field, enter prconfig/database/databases/pegasearch/searchendpoint/default.
5. Click Create and open.
6. In the Value field, enter the Elasticsearch server's host name and port in the following format: http://<hostname>:<port>
7. Restart all Pega nodes.

To modify the prconfig.xml file:

1. Add the following line to the prconfig.xml file on each server: <env name="database/databases/pegasearch/searchendpoint" value="http://<hostname>:<port>"
2. Restart all Pega nodes. 

Verify that search is enabled and that the Elasticsearch endpoint is in the expected http://<hostname>:<port> format:

1. On Pega Platform, in Dev Studio, click Configure > System > Search.
2. In the Settings section, in the Elasticsearch Server endpoint field, verify that Elasticsearch has been configured correctly. If the status is available or incomplete for All rules and All data, Elasticsearch has been configured correctly. An incomplete status indicates that reindexing is occurring.