Installing OpenSearch

Subscription Required

You can connect OpenSearch with Liferay. For detailed OpenSearch installation and configuration instructions, consult the OpenSearch documentation.

Download the OpenSearch Connector

Warning

Do not install the OpenSearch connector into Liferay until the blacklist and connector configurations are in place and OpenSearch is running.

From https://marketplace.liferay.com/, click Account → Sign In.
Search for OpenSearch and select the Liferay Connector to OpenSearch 2 connector.
Click the Get App button on the OpenSearch landing page.
Choose a project if it exists, or add one.
Agree to the conditions and click Get App.
After purchasing, go to your dashboard and download the app’s zip file.
Extract the LPKG to a temporary folder.

Refer to the Search Engine Compatibility Matrix for the compatible application versions for your Liferay version and patch level.

Environment Setup for Production-Like Installation

For a production-like setup on your local machine, add the hosts for Liferay and the OpenSearch cluster. Add this information to your operating system’s path/to/etc/hosts file:

<your IP> os-node1
<your IP> os-node2
<your IP> os-node3
<your IP> dxp.liferay.com

Use the real IP address of your system, not the loopback address 127.0.0.1.

You can skip this if setting up a local testing environment.

Install and Configure OpenSearch

Before installing OpenSearch on a production server, review the recommended system settings. Static settings in OpenSearch are configured with its [OpenSearch Home]/config/opensearch.yml file or through startup environment variables.

Note

For OpenSearch 2.12 or later, set an environment variable with an initial admin password before installing OpenSearch:

export OPENSEARCH_INITIAL_ADMIN_PASSWORD=[initial-admin-password]

Additionally, prepare your security certificates for OpenSearch: transport layer, HTTP layer, and admin certificates may be needed. Although OpenSearch defaults to using PEM certificates, you must use PKCS#12 certificates with Liferay. See the relevant OpenSearch documentation:

The main OpenSearch settings to configure for Liferay are those that correspond to Liferay’s OpenSearch Connector properties:

discovery.type
network.host
http.port
node.name
transport.port
plugins.security.*

In addition to these fundamental connection configurations, increasing the indices.query.bool.max_clause_count setting (defaults to 1024) can help prevent errors such as field expansion for [*] matches too many fields and query contains too many nested clauses; maxClauseCount is set to 1024. Consider setting this to 1024 * [Heap Size in GB]. For example, a 4GB heap size in OpenSearch should use a max clauses count value of 4096.

Here’s an example opensearch.yml configuration for one node of a cluster, using the same certificates for the transport and HTTP layers:

indices.query.bool.max_clause_count: 4096

cluster.name: LiferayOpenSearchCluster
http.port: 9200
network.host: os-node1
node.name: os-node1
transport.port: 9300

discovery.seed_hosts: ["os-node1", "os-node2", "os-node3"]
cluster.initial_cluster_manager_nodes: ["os-node1", "os-node2", "os-node3"]

# Transport SSL
plugins.security.ssl.transport.enabled: true
plugins.security.ssl.transport.keystore_type: PKCS12
plugins.security.ssl.transport.keystore_filepath: certs/keystore.p12
plugins.security.ssl.transport.keystore_password: liferay

plugins.security.ssl.transport.truststore_type: PKCS12
plugins.security.ssl.transport.truststore_filepath: certs/truststore.p12
plugins.security.ssl.transport.truststore_password: liferay2

# HTTP SSL
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.keystore_type: PKCS12
plugins.security.ssl.http.keystore_filepath: certs/keystore.p12
plugins.security.ssl.http.keystore_password: liferay

plugins.security.ssl.http.truststore_type: PKCS12
plugins.security.ssl.http.truststore_filepath: certs/truststore.p12
plugins.security.ssl.http.truststore_password: liferay2

# Certficiate Distinguished Names
plugins.security.nodes_dn:
  - 'CN=os-node1,OU=KM,O=Liferay,L=DiamondBar,ST=California,C=US'
  - 'CN=os-node2,OU=KM,O=Liferay,L=DiamondBar,ST=California,C=US'
  - 'CN=os-node3,OU=KM,O=Liferay,L=DiamondBar,ST=California,C=US'

plugins.security.authcz.admin_dn:
  - 'CN=kirk,OU=client,O=client,L=test,C=de'

The keystore and truststore files must be within the [OpenSearch Home]/config folder.

If you’re testing locally, you can simplify the setup by making some configuration changes. These settings must not be included in production environments:

# Only bind to the local loopback interface
network.host: _local_
# Specify a single-node cluster
discovery.type: single-node
# Generate the secruity index at startup
plugins.security.allow_default_init_securityindex: true
# Do not verify hostnames in the transport layer: this is not needed with a single node cluster
# plugins.security.ssl.transport.enforce_hostname_verification: false

Start OpenSearch with ./bin/opensearch.

Liferay requires that some analysis plugins are installed into OpenSearch. Even if your instance doesn’t need functionality from these plugins, Liferay requires them. Install the required analysis plugins into the running OpenSearch with the opensearch-plugin tool:

./bin/opensearch-plugin install analysis-icu analysis-kuromoji analysis-smartcn analysis-stempel

Verify the connection by running

curl https://localhost:9200 -ku 'admin:admin-pass'

Connecting to Liferay

Before starting Liferay, provide the configurations for disabling Elasticsearch and the features that do not work with OpenSearch, and for connecting to OpenSearch.

Disable Elasticsearch-Specific Modules

Add a blacklist configuration file in [Liferay Home]/dxp/files/osgi/configs called com.liferay.portal.bundle.blacklist.internal.configuration.BundleBlacklistConfiguration.config with this configuration:

blacklistBundleSymbolicNames=[\
 "com.liferay.portal.search.elasticsearch.cross.cluster.replication.impl",\
 "com.liferay.portal.search.elasticsearch.monitoring.web",\
 "com.liferay.portal.search.elasticsearch7.api",\
 "com.liferay.portal.search.elasticsearch7.impl",\
 "com.liferay.portal.search.learning.to.rank.api",\
 "com.liferay.portal.search.learning.to.rank.impl"\
]

Configure the OpenSearch Connector

To specify the properties for connecting Liferay with OpenSearch, create the file com.liferay.portal.search.opensearch2.configuration.OpenSearchConfiguration.config in [Liferay Home]/dxp/files/osgi/configs with this configuration:

remoteClusterConnectionId="REMOTE"

Next, create the configuration for the remote cluster you configured above in the file com.liferay.portal.search.opensearch2.configuration.OpenSearchConnectionConfiguration-REMOTE.config.

For a complete list of Liferay’s OpenSearch Connector configurations, see OpenSearch Connector Configuration Reference.

active=B"true"
authenticationEnabled=B"true"
connectionId="REMOTE"
httpSSLEnabled=B"true"
logExceptionsOnly=B"false"
networkHostAddresses=["https://os-node1:9200","https://os-node3:9201","https://os-node3:9202"]
password="liferay-user-password"
truststorePassword="certpass"
truststorePath="/path/to/certs/truststore.p12"
truststoreType="pkcs12"
username="liferay"

Once the configurations are in place, start Liferay.

Start Liferay and Reindex

If OpenSearch is installed and running, start Liferay. In the Control Panel, navigate to Configuration → Search and verify the OpenSearch connection is active.

Reindex the search indexes and spell check indexes. Invoke both of these actions in the Index Actions tab of Control Panel → Configuration → Search.

Capability: