Configuring the Liferay Elasticsearch Connector (6.1)

For detailed Elasticsearch configuration information, refer to the Elasticsearch documentation.

The name of your Elasticsearch cluster is important. When you’re running Elasticsearch in remote mode, the cluster name is used by Liferay DXP to recognize the Elasticsearch cluster. To learn about setting the Elasticsearch cluster name on the Liferay DXP side, refer below to the section called Configuring the Liferay Elasticsearch Connector.

Elasticsearch’s configuration files are written in YAML and kept in the [Elasticsearch Home]/config folder:

  • elasticsearch.yml is for configuring Elasticsearch modules
  • logging.yml is for configuring Elasticsearch logging

To set the name of the Elasticsearch cluster, open [Elasticsearch Home]/config/elasticsearch.yml and specify LiferayElasticsearchCluster

Since LiferayElasticsearchCluster is the default name given to the cluster, this would work just fine. Of course, you can name your cluster whatever you’d like (we humbly submit the recommendation clustery_mcclusterface).1 You can configure your node name using the same syntax (setting the property).

If you’d rather work from the command line than in the configuration file, navigate to Elasticsearch Home and enter

./bin/elasticsearch clustery_mcclusterface nody_mcnodeface

Feel free to change the node name or the cluster name. Once you configure Elasticsearch to your liking, start it up.

Starting Elasticsearch

Start Elasticsearch by navigating to Elasticsearch Home and typing


if you run Linux, or


if you run Windows.

To run as a daemon in the background, add the -d switch to either command:

./bin/elasticsearch -d

Once both Elasticsearch and Liferay DXP are installed and running, introduce Liferay DXP and Elasticsearch to each other.

Configuring the Liferay Elasticsearch Connector

The Elasticsearch connector provides integration between Elasticsearch and Liferay DXP. Before you configure the connector, make sure Elasticsearch is running.

There are two ways to configure the adapter:

  1. Use the System Settings application in the Control Panel.

  2. Manually create an OSGi configuration file.

It’s convenient to configure the Elasticsearch adapter from System Settings, but this is often only possible during development and testing. If you’re not familiar with System Settings, you can read about it here. Remember that you can generate configuration files for deployment to other systems by configuring System Settings, and then exporting the .config file with your configuration.

Configuring the Adapter in the Control Panel

Here’s how to configure the Elasticsearch adapter from the System Settings application:

  1. Start Liferay DXP.

  2. Navigate to Control PanelConfigurationSystem SettingsFoundation.

  3. Find the Elasticsearch entry (scroll down and browse to it or use the search box) and click the Actions icon (Actions), then Edit.

    Figure 1: Use the System Settings application in Liferay DXPs Control Panel to configure the Elasticsearch adapter.

    Figure 1: Use the System Settings application in Liferay DXP's Control Panel to configure the Elasticsearch adapter.

  4. Make any edits to the configuration and click Save.

    Figure 2: Set configurations for the Elasticsearch connector, like settings the Operation Mode to Remote.

    Figure 2: Set configurations for the Elasticsearch connector, like settings the Operation Mode to *Remote*.

Configuring the Adapter with an OSGi .config File

When preparing a system for production deployment, you should have a repeatable deployment process. Therefore, it’s best to use the OSGi configuration file, where your configuration is maintained in a controlled source.

Follow these steps to configure the Elasticsearch adapter using an OSGi configuration file:

  1. Create the following file:

  2. Add configurations to the file, in the format propertyName="Value". For example,

     # If running Elasticsearch from a different computer:
     # Highly recommended for all non-prodcution usage (e.g., practice, tests, diagnostics):
  3. Start Liferay DXP or re-index if already running.

As you can see from the System Settings entry for Elasticsearch, there are a lot more configuration options available that help you tune your system for optimal performance.

What follows here are some known good configurations for clustering Elasticsearch. These, however, can’t replace the manual process of tuning, testing under load, and tuning again, so we encourage you to examine the

Elasticsearch documentation and go through that process once you have a working configuration.

Configuring a Remote Elasticsearch Host

In production systems Elasticsearch and Liferay DXP are installed on different servers. To make Liferay DXP aware of the Elasticsearch cluster, set

transportAddresses=[IP address of Elasticsearch Node]:9300

Here’s an example that sets the IP address of two nodes in the Elasticsearch cluster:


Set this in the Elasticsearch connector’s OSGi configuration file. List as many Elasticsearch nodes in this property as you want. This tells Liferay DXP the IP address or host name where search requests should be sent. If using System Settings, set the value in the Transport Addresses property.

On the Elasticsearch side, set the property in your elaticsearch.yml file. This property simultaneously sets both the bind host (the host where Elasticsearch listens for requests) and the publish host (the host name or IP address Elasticsearch uses to communicate with other nodes). See here for more information.

Clustering Elasticsearch in Remote Operation Mode

Clustering Elasticsearch is easy. First, set node.max_local_storage_nodes to be something greater than 1. When you run the Elasticsearch start script, a new local storage node is added to the cluster. If you want four nodes running locally, for example, run ./bin/elasticsearch four times. See here for more information.

Configure the number of shards and replicas in the Elasticsearch 6 adapter, using the indexNumberOfShards and indexNumberOfReplicas properties to specify the number of primary shards and number of replica shards, respectively. Elasticsearch’s default configuration works for a cluster of up to ten nodes, since the default number of shards is 5 and the default number of replica shards is 1.

For more information on configuring an Elasticsearch cluster, see the documentation on Elasticsearch Index Settings.

Elasticsearch Connector System Settings, By Operation Mode

Some of the settings available for the Elasticsearch connector are applicable for only one operation mode (REMOTe or EMBEDDED). Refer to the table below:

Adapter Setting/Operation ModeEMBEDDEDREMOTE

* Note: Available in the Connector to Elasticsearch 6 only.

1 This is, of course, a nod to all those fans of Boaty Mcboatface.

« Installing Elasticsearch 6.1Advanced Configuration of the Liferay Elasticsearch Connector (6.1) »
Was this article helpful?
1 out of 1 found this helpful