Connecting to Elasticsearch¶
Liferay 7.3: Liferay Connector to Elasticsearch is included in the Liferay DXP 7.3 and CE 7.3 GA4+. It’s also available on Liferay Marketplace.
Liferay 7.2: Liferay Connector to Elasticsearch is available on Liferay Marketplace.
Notable installation and configuration procedure differences are presented here.
Stop each Liferay server node before configuring the connection.
If you’re on Liferay 7.2, skip to Liferay 7.2: Installing Elasticsearch 7 Connector.
Configuring the Connector¶
The Elasticsearch 7 connector is configured for Liferay 7.3 via a configuration file named
After specifying the configuration in the file, you can deploy it by placing it into your
[Liferay Home]/osgi/configs/ folder.
docker cp ~/path/to/com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config [container]:/mnt/liferay/files
Alternatively, you can configure the connector in the user interface. In the Global Menu (), go to Control Panel → System Settings and open the Search category. The entry is called Elasticsearch 7.
In Liferay 7.2, The Control Panel is in the Product Menu ().
A simple 7.3 connector configuration enables production mode (
productionModeEnabled="true") and sets the URL to each Elasticsearch node (
Create the following configuration file:
Specify the configuration properties in the
.configfile. Here’s an example that includes security properties commented out (note that you’d need to use
httpsnetwork host addresses when encryption is enabled):
# In CE/DXP7.3, productionModeEnabled replaces operationMode (deprecated): productionModeEnabled=B"true" networkHostAddresses=["http://es-node1:9200","http://es-node3:9201","http://es-node3:9202"] # In CE/DXP 7.3 the security settings are included in the ElasticsearchConfiguration # In CE/DXP 7.2 the security settings go in com.liferay.portal.search.elasticsearch7.configuration.XPackSecurityConfiguration.config # Authentication #authenticationEnabled=B"true" #username="elastic" #password="liferay" # TLS/SSL #networkHostAddresses=["https://es-node1:9200","https://es-node3:9201","https://es-node3:9202"] #httpSSLEnabled=B"true" #truststoreType="pkcs12" #trustStorePath="/PATH/TO/elastic-nodes.p12" #trustStorePassword="liferay" # Highly recommended for all non-prodcution usage (e.g., practice, tests, diagnostics): #logExceptionsOnly="false"
.configfile in your
To refer to Elasticsearch servers by name, map each Elasticsearch server name to its IP address in your DNS or your Liferay server’s
The network host address format is
http[s]://[host name]:[port]. If you’re using a Liferay Docker container, you can use
--add-host [host name]:[IP address] options with your
docker run command to map a host name to each Elasticsearch server IP address. The port is defined in the Elasticsearch container’s docker run command as the first value of the
-p 1234:5678 option (it’s
1234 in this case). If you’re running a local test environment without HTTPS enabled, all the addresses can be
http://localhost:port. See Docker’s documentation for more details.
Liferay 7.2: Installing Elasticsearch 7 Connector¶
Stop the Elasticsearch 6 Connector¶
On Liferay 7.2, the bundled connector application and APIs are for Elasticsearch 6. These must be disabled before installing the Elasticsearch 7 connector.
Create a file called
Add this content to the file:
blacklistBundleSymbolicNames=[ \ "com.liferay.portal.search.elasticsearch6.api", \ "com.liferay.portal.search.elasticsearch6.impl", \ "com.liferay.portal.search.elasticsearch6.spi", \ "com.liferay.portal.search.elasticsearch6.xpack.security.impl", \ "Liferay Connector to X-Pack Security [Elastic Stack 6.x] - Impl", \ "Liferay Enterprise Search Security - Impl.lpkg" \ ]
Place the file in your
When you start the Liferay server (not yet), Liferay reads this file and blocks the declared bundles from starting.
Liferay Homeand other important folders of a Liferay installation are accessed in a Docker container at
/mnt/liferayas described here. You can use
docker cp /path/to/local/file [container_name]:/mnt/liferay/files/osgi/configsto place configuration files into the container. Later, you can use
docker cpto deploy the Liferay Connector to Elasticsearch 7 LPKG file.
Install the Elasticsearch 7 Connector¶
Download the Liferay Connector to Elasticsearch 7.
Make sure the connector corresponds to your Elasticsearch version. Note, the client libraries in the connector can be for an older version of Elasticsearch (e.g., 7.3) even though the connector application supports a newer version (e.g., 7.9.x). Liferay tests the connector with every minor Elasticsearch version and creates new update connector versions when needed. As always, consult the Search Engine Compatibility Matrix for connector compatibility.
Install the LPKG by placing it in the folder
docker cp ~/path/to/Liferay\ Connector\ to\ Elasticsearch.lpkg [container]:/mnt/liferay/deploy
When you start the Liferay server (not yet), Liferay deploys the LPKG.
You’re ready to configure the connector.
Configure the Connector for Liferay 7.2¶
Create the following Elasticsearch configuration file:
Specify the configuration properties in the
.configfile. Here’s an example that enables remote operation mode, sets the transport address for each Elasticsearch node, and identifies the connection you’re configuring:
# com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config operationMode="REMOTE" transportAddresses="ip.of.elasticsearch.node:9300" # Highly recommended for all non-production usage (e.g., practice, tests, diagnostics): #logExceptionsOnly="false"
Deploy the configuration by placing the
.configfile in your
You’re ready to start Liferay.
Start Liferay and Re-Index¶
If Elasticsearch is installed and running, start Liferay. In the Control Panel, navigate to Configuration → Search and verify the Elasticsearch connection is active.
Re-index your search indexes and spell check indexes. Invoke both of these actions in the Index Actions tab of Control Panel → Configuration → Search.
On Liferay 7.3, Re-index the Workflow Metrics indexes from the Workflow Metrics Settings window:
From the Global Menu () navigate to Applications → Workflow Metrics.
Open the Settings window from the App Options menu ().
Click Reindex All.
If you have Elasticsearch indexes used for primary data storage (storing data not backed by a database) you can bring that data into your new Elasticsearch cluster using the snapshot and restore approach. Liferay’s own Search Tuning indexes (for Result Rankings and Synyonyms) are primary storage indexes.
Now Liferay is indexing content into your remote Elasticsearch 7 installation.
Available Liferay Elasticsearch Connectors¶
The bundled connector to Elasticsearch is not always the best choice for your installation. It’s important to understand the differences between the connectors you can use to communicate with Elasticsearch:
|Liferay CE/DXP Version||Name||Availability||Communication Protocol||Supports Secure Connection||Operation Modes|
|CE 7.3 GA4+, DXP 7.3 GA1+||Liferay (CE) Connector to Elasticsearch 7||Bundled||HTTP||✔||Sidecar / Remote (Production)*|
|CE 7.2, DXP 7.2||Liferay Connector (CE) to Elasticsearch 6||Bundled||Transport||✔** (requires LES)||Embedded / Remote|
|CE 7.2, DXP 7.2||Liferay Connector (CE) to Elasticsearch 7 (v3.x)||Marketplace: CE, DXP||Transport||✔||Embedded / Remote|
* The connector configuration’s Operation Mode (
operationMode) setting is deprecated and replaced with Production Mode Enabled (
** Through the Liferay Enterprise Search Security application.
For detailed compatibility information, including the compatible Elasticsearch versions and required patch levels, see the Search Engine Compatibility Matrix.