Configuring the Liferay Elasticsearch Connector

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. The main configuration file is elasticsearch.yml, used for configuring Elasticsearch modules.

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 in the Liferay DXP Elasticsearch connector, this works just fine. Of course, you can name your cluster whatever you want (we humbly submit the recommendation clustery_mcclusterface).1 Configure your node name using the same syntax (setting the property). There’s no client setting for this, it exists only in each Elasticsearch node’s elasticsearch.yml file.

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 them to each other.

Configuring the Liferay Elasticsearch Connector

The Elasticsearch connector provides integration between Elasticsearch and the portal. Before configuring the connector, make sure Elasticsearch is running.

There are two ways to configure the connector:

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

  2. Manually create an OSGi configuration file.

It’s convenient to configure the Elasticsearch connector from System Settings, but this is often only possible during development and testing. If you’re not familiar with System Settings, 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 Connector in the Control Panel

To configure the Elasticsearch connector from the System Settings application,

  1. Start Liferay DXP.

  2. Navigate to Control PanelConfigurationSystem SettingsPlatform.

  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 connector.

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

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

    Figure 2: Configure the Elasticsearch connectors settings. Make sure you set the Operation Mode to Remote.

    Figure 2: Configure the Elasticsearch connector's settings. Make sure you set the Operation Mode to *Remote*.

Configuring the Connector with an OSGi .config File

When preparing a system for production deployment, you want to use 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 connector using a 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-production 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 or as few 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

To cluster Elasticsearch, 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 connector, 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.

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:

Connector Setting/Operation ModeEMBEDDEDREMOTE

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

« Installing ElasticsearchAdvanced Configuration of the Liferay Elasticsearch Connector »
Was this article helpful?
0 out of 1 found this helpful