Installing OpenSearch

Subscription Required Liferay DXP 2025.Q1+

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

Download the OpenSearch Connector

1. From https://marketplace.liferay.com/, click Account → Sign In.

2. Search for Liferay Connector to OpenSearch 2, open the app’s page, and click Get App.

3. Choose a project if it exists, or add one.

4. Agree to the conditions and click Get App.

5. After purchasing, go to your dashboard and download the app’s LPKG file.

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

Configure Your Hosts File

To use named hosts for Liferay and the OpenSearch cluster, add them to your operating system’s /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.

This step is optional for a minimal local test but required when using named hosts in the OpenSearch and connector configurations. For a quick local setup using Docker, see Exercise: Run Liferay and OpenSearch Using Docker.

Generate Security Certificates

Generate security certificates before configuring OpenSearch. OpenSearch nodes use certificates for the transport layer (inter-node communication) and the HTTP layer (client connections). The steps below create a certificate authority (CA), sign a node certificate covering all cluster hostnames, and produce a PKCS#12 keystore for the OpenSearch nodes and a separate truststore for Liferay. PKCS#12 is supported by both OpenSearch and the JDK. OpenSearch also supports PEM format — see Configuring TLS Certificates and Generating Self-Signed Certificates in the OpenSearch documentation for alternatives.

1. Generate a certificate authority (CA):

   openssl genrsa -out ca.key 2048
   openssl req -x509 -new -nodes -key ca.key -sha256 -days 730 \
     -out ca.pem -subj "/CN=OpenSearch-CA"
   

2. Generate a node key and certificate signing request. To use the same certificate on all nodes, list each node hostname as a subject alternative name:

   openssl genrsa -out node.key 2048
   openssl req -new -key node.key -out node.csr -subj "/CN=os-node1"
   printf 'subjectAltName=DNS:os-node1,DNS:os-node2,DNS:os-node3' > node.ext
   

3. Sign the certificate with the CA:

   openssl x509 -req -sha256 -days 730 \
     -in node.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
     -out node.pem -extfile node.ext
   

4. Create the keystore for OpenSearch nodes:

   openssl pkcs12 -export \
     -in node.pem -inkey node.key \
     -out keystore.p12 -passout pass:liferay
   

5. Create the truststore for Liferay. The truststore contains the CA certificate so Liferay can verify OpenSearch’s certificate:

   openssl pkcs12 -export -nokeys \
     -in ca.pem \
     -out truststore.p12 -passout pass:certpass
   

Move keystore.p12 and truststore.p12 to the [OpenSearch Home]/config/certs folder on each OpenSearch node. Copy truststore.p12 to an accessible path on the Liferay server.

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.

export OPENSEARCH_INITIAL_ADMIN_PASSWORD=[initial-admin-password]

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'

Create a Liferay User in OpenSearch

Before connecting Liferay, create a dedicated OpenSearch user for Liferay to authenticate with. See Create users in the OpenSearch documentation. Use the new user’s credentials for the username and password fields in the connection configuration below.

Connect 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 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.elasticsearch8.api",\
 "com.liferay.portal.search.elasticsearch8.impl",\
 "com.liferay.portal.search.learning.to.rank.api",\
 "com.liferay.portal.search.learning.to.rank.impl"\
]

Configure the OpenSearch Connector

Before deploying the connector, specify the Liferay-OpenSearch connection properties.

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, deploy the connector.

Deploy the OpenSearch Connector

With Elasticsearch modules blacklisted, the connector configured, and OpenSearch running, deploy the LPKG before starting Liferay:

• For a traditional installation, copy the LPKG into the [Liferay Home]/deploy folder.

• For Docker, copy the LPKG into the host folder bind-mounted to the container’s /opt/liferay/deploy (see Exercise: Run Liferay and OpenSearch Using Docker for an example setup).

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.

Related Topics

• Installing Elasticsearch
• Search Pages and Widgets
• Search Blueprints