On-Premises Initial Setup for Elasticsearch

The following one-time set up is required to prepare STEP for using the Elasticsearch search engine to configure a modern faceted search experience for on-premises.

Note: Elasticsearch can display product, entity, classification, and/or asset data only, based on configuration.

Important: Before starting the configuration outlined in this topic, contact Stibo Systems to activate Elasticsearch.

Configuration

Using Elasticsearch with STEP requires an external installation process of Elasticsearch 8.12.1. For more information on Elasticsearch, search https://www.elastic.co/.

Important: Stibo Systems exclusively supports the Elasticsearch cloud service distributed from Elastic.
Review the Important note above and contact Stibo Systems to enable the Elasticsearch license on your system.
Review the Important note above and activate the 'elasticsearch-integration' component. For on-premises systems, instructions for installing components can be found in the 'SPOT Program' topic in the System Administration documentation found in 'Downloadable Documentation'. For Stibo Systems SaaS environments, contact Stibo Systems Support.

Important: SaaS systems should automatically upgrade when new Elasticsearch versions are made available. However, on-premise systems will need to be manually upgraded to the new Elasticsearch version.
Review the Important notes above and activate the 'ui-search' component. For on-premises systems, instructions for installing components can be found in the 'SPOT Program' topic in the System Administration documentation found in 'Downloadable Documentation'. For Stibo Systems SaaS environments, contact Stibo Systems Support.
Add the Elasticsearch cluster name and port, separated by a colon (:), in the sharedconfig.properties file on the STEP application server using the case-sensitive Elasticsearch.Cluster.Nodes property as shown below:
```
Elasticsearch.Cluster.Nodes=http://elasticsearch:9200
```
In this example, 'http://elasticsearch' is the name of the cluster and '9200' is the port.
In the sharedconfig.properties file on the STEP application server, the case-sensitive Elasticsearch.Query.CacheRetentionTime property determines the number of seconds it takes for changes to the Elasticsearch Configuration to be reflected in the Web UI. The default setting is 600 seconds (10 minutes), which is optimized for performance. If you would like to change the frequency of updates, modify this setting.
```
Elasticsearch.Query.CacheRetentionTime=600
```
In this example, the default has not been changed.
In the sharedconfig.properties file on the STEP application server, the case-sensitive Elasticsearch.NumberOfReplicas and Elasticsearch.NumberOfShards properties make it possible to configure the replicas (default 0) and shards (default 1) to be used for the indexes created by STEP. If you need help to configure these properties to match the Elasticsearch setup, contact Stibo Systems Support.

For troubleshooting an event processor 'maximum shards open' error, refer to the Elasticsearch Index Publishing topic.

If required, in the sharedconfig.properties file on the STEP application server, the case-sensitive properties below will allow you to connect via proxy (the properties to the right of the equal sign are examples only):
```
Elasticsearch.Proxy.Host=sample.stibo.com
Elasticsearch.Proxy.Port=3248
Elasticsearch.Proxy.User=username
Elasticsearch.Proxy.Password=password
```

Kibana is a tool for troubleshooting unexpected Elasticsearch results on the Search Screen. The installed Kibana version must be the same as the installed version of Elasticsearch. The latest versions supported are included in release notes. For more information, search the web.

Changes to the properties file, outlined above, are implemented when the server is restarted.

Note: In instances where the STEP system is set up with both an internal and an external address ( i.e., a load balancer or other network gateway between client and server), the System.ClientName property should be used to let the STEP system know that all external URLs, such as those used for image resources, need to be created with the external base URL.

Next, create an Elasticsearch object type as defined in the Creating an Elasticsearch Object Type topic.