Documentation

Documentation Menu
Go Back

Installing Solr

Solr is a popular enterprise search platform built on Apache Lucene. It’s reliable, scalable, and fault tolerant. Read more about it here.

These instructions describe installing Solr 8 for Liferay 7.1 through 7.3. They apply equally to installing Solr 7 for Liferay 7.1-7.2, but some adjustments for version name may be necessary.

Important

  • Liferay’s Solr support is deprecated; Solr 8 is the last supported Solr version. Please plan to migrate to Elasticsearch.

  • There are important limitations to be aware of when installing Solr. Read Solr Limitations_ before proceeding with the installation.

As you proceed, remember these terms:

Solr Home: Refers to solr-[version]/server/solr/, the main Solr configuration directory. This is where the Liferay core will be configured.

Liferay Home: The root folder of your Liferay installation. It contains the osgi, deploy, data, and license folders, among others.

Compatibility

See the Search Engine Compatibility Matrix for detailed information on the compatible Solr and Liferay versions by patch level.

Disabling Elasticsearch-Only Features

Before installing the Liferay Connector to Solr, you must blacklist or otherwise disable

  • the modules for certain DXP features that only work with Elasticsearch

  • the Liferay Connector to Elasticsearch’s modules

Tip

Use the Gogo shell command lb [substring-to-search] -s to search for modules deployed to the OSGi runtime and list them by their Symbolic Name. The Symbolic Name is the value to enter in the blacklistBundleSymbolicNames property.

The following command returns the list of modules that must be blacklisted:

lb -s | grep 'search' | grep 'elasticsearch|tuning'

Blacklisting Elasticsearch-Only Features

If you’re a Liferay DXP customer you should use the blacklist feature to disable the Elasticsearch-only features. CE users can also use this approach:

  1. Create a configuration file named

    com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config

  2. Give it these contents:

    blacklistBundleSymbolicNames=[\
     "com.liferay.portal.search.elasticsearch6.api",\
     "com.liferay.portal.search.elasticsearch6.impl",\
     "com.liferay.portal.search.elasticsearch6.spi",\
     "com.liferay.portal.search.elasticsearch7.api",\
     "com.liferay.portal.search.elasticsearch7.impl",\
     "com.liferay.portal.search.elasticsearch7.spi",\
     "com.liferay.portal.search.tuning.rankings.web",\
     "com.liferay.portal.search.tuning.synonyms.web",\
     "com.liferay.portal.search.tuning.web",\
     "com.liferay.portal.search.tuning.web.api"\
]

  3. Place the file in Liferay Home/osgi/configs.

Stopping the Modules with Elasticsearch-Only Features

The App Manager and Gogo shell rely on the osgi/state folder to “remember” the state of the bundle. If you delete this folder (recommended during patching Liferay DXP) the Elasticsearch connector is reinstalled and started automatically. Liferay CE users can use the blacklist approach or disable the Elasticsearch and search tuning modules in the App Manager or the Gogo shell.

To disable via App Manager,

  1. Navigate to Control Panel → Apps → App Manager.

  2. Once in the App Manager, search for elasticsearch. Find the Liferay Connector to Elasticsearch 6/7 modules and open the Actions (Actions) menu. Choose Deactivate. This leaves the bundle installed, but stops it in the OSGi runtime. Do the same for the search tuning modules.

To use the Felix Gogo shell to stop the Elasticsearch and search tuning modules,

  1. Enter lb -s | grep 'search' | grep 'elasticsearch|tuning'

    You’ll see several active bundles for the connector to Elasticsearch and the search tuning modules.

  2. For each bundle listed enter stop [bundle ID].

Downloading the Solr Connector

To install the Liferay Connector to Solr [7 or 8], navigate to Liferay Marketplace and download the app version that corresponds to your Liferay version.

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

Installing and Configuring Solr

Before proceeding, stop the Liferay instance.

To install and properly configure Solr for Liferay:

  1. Download a compatible Solr server and unzip it. The below links are for convenience only and represent the latest compatible Solr version at the time of writing. See the Search Engine Compatibility Matrix to see if newer compatible versions are available. We are using the following versions in this guide as an example:

  2. Navigate to Solr Home (solr-[version]/server/solr) and create a new folder called liferay.

  3. Create two new subfolders: liferay/conf and liferay/data.

  4. Copy the contents of Solr_Home/configsets/_default/conf to Solr_Home/liferay/conf.

  5. Open the Liferay Connector to Solr 8’s LPKG file with an archive manager.

    Next open the Liferay Connector to Solr 7/8 - Impl.lpkg.

    Finally, open the com.liferay.portal.search.solr7/8.impl.jar file, and extract

    META-INF/resources/solrconfig.xml

    and

    META-INF/resources/schema.xml

    to

    Solr_Home/liferay/conf

    This replaces the current solrconfig.xml and schema.xml files with ones that tell Solr how to index data coming from Liferay.

  6. Create a core.properties file in Solr_Home/liferay and add this configuration:

    config=solrconfig.xml
dataDir=data
name=liferay
schema=schema.xml

  7. Checkpoint: your Solr_Home/liferay folder now has this structure:

    liferay
├── conf
│   ├── lang
│   │   ├── contractions_ca.txt
│   │   ├── ....txt
│   ├── managed-schema
│   ├── protwords.txt
│   ├── schema.xml
│   ├── solrconfig.xml
│   ├── stopwords.txt
│   └── synonyms.txt
├── core.properties
└── data

  8. Start the Solr server by entering the following from the top-level folder of your Solr installation (solr-[version]):

    ./bin/solr start -f

  9. The Solr server listens on port 8983 by default. Navigate to http://localhost:8983/solr/#/~cores (assuming you’re testing locally with localhost as your host), and confirm that the liferay core is available.

Solr is now installed and started. Next configure and install the Solr connector for Liferay.

Installing and Configuring the Solr Connector

The default connector configuration works for a test installation because the default configurations in the Liferay Connector to Solr match Solr’s own defaults. See the Configuration Reference for the complete list of available settings. At a minimum, the read and write URLs must be configured for the connector in production environments.

In production deployments it’s most common to make your edits to the Solr connector’s default configurations using a configuration file deployed to the Liferay_Home/osgi/configs folder:

  1. Name the file

com.liferay.portal.search.solr8.configuration.SolrConfiguration.config

or

com.liferay.portal.search.solr7.configuration.SolrConfiguration.config

You can alternatively use the UI for configuring the connector. Find the Solr 7 System Settings entry in Control Panel → Configuration → System Settings.

You can configure Solr from Liferay's System Settings application. This is most useful during development and testing.

  1. Once the app LPKG is downloaded, copy it to Liferay_Home/osgi/marketplace and put any configuration files in Liferay_Home/osgi/configs.

  2. Start Liferay.

  3. Re-index your Liferay data into Solr. Open the Global Menu and navigate to Control Panel → Configuration → Search. In the Index Actions pane, click Execute next to the Reindex all search indexes option.

    Re-index the spell check indexes too.

    The Solr connection can be verified in the Search administration console.

High Availability with SolrCloud

Use SolrCloud if you need a cluster of Solr servers. Note that to use SolrCloud in production, you should set up an external ZooKeeper ensemble. ZooKeeper is a centralized coordination service for managing distributed systems like your SolrCloud cluster.

The steps included here should be considered the bare minimum of what must be done to configure SolrCloud with Liferay. For example, these instructions cover configuring SolrCloud on a single machine, whereas a production environment would feature multiple physical or virtual machines. These instructions also assume you’ve followed the earlier section on Installing and Configuring Solr. Refer to the SolrCloud guide for more information.

  1. Stop the Solr server if it’s running.

  2. Navigate to the Solr_Home/configsets folder and create a folder called

    liferay_configs

  3. Copy the conf folder from Solr_Home/liferay to the liferay_configs folder you just created.

    The configset/liferay_configs folder contains the SolrCloud Liferay collection configuration and is uploaded to ZooKeeper. When you copy the conf folder from the liferay server configured earlier, you use the schema.xml and solrconfig.xml files provided with the Liferay Solr Adapter.

  4. Launch an interactive SolrCloud session to configure your SolrCloud cluster:

    ./bin/solr -e cloud

  5. Complete the setup wizard. These steps demonstrate creating a two-node cluster:

    • Enter 2 for the number of nodes.

    • Specify ports 8983 and 7574 (the defaults). Both nodes are started with the start commands printed in the log:

      Starting up Solr on port 8983 using command:
"bin/solr" start -cloud -p 8983 -s "example/cloud/node1/solr"

Waiting up to 180 seconds to see Solr running on port 8983 [|]  [-]  
Started Solr server on port 8983 (pid=8846). Happy searching!

    
Starting up Solr on port 7574 using command:
"bin/solr" start -cloud -p 7574 -s "example/cloud/node2/solr" -z localhost:9983

Waiting up to 180 seconds to see Solr running on port 7574 [|]  [/]  
Started Solr server on port 7574 (pid=9026). Happy searching!

    • Name the collection liferay.

    • Split the collection into two shards.

    • Specify two replicas per shard.

    • When prompted to choose a configuration, enter liferay_configs. You should see a log message that concludes like this when the cluster has been started:

    SolrCloud example running, please visit http://localhost:8983/solr

Now you have a new collection called liferay in your local SolrCloud cluster. Verify its status by running the status command:

./bin/solr status

The log output states that the nodes are found and lists information for each node:

Found 2 Solr nodes: 

Solr process 223597 running on port 8983
{
  "solr_home":"/home/user/liferay-bundles/solr8_7.3/solr-8.6.3/example/cloud/node1/solr",
  "version":"8.6.3 e001c2221812a0ba9e9378855040ce72f93eced4 - jasongerlowski - 2020-10-03 18:12:03",
  "startTime":"2021-03-23T18:26:45.450Z",
  "uptime":"0 days, 0 hours, 25 minutes, 4 seconds",
  "memory":"306.5 MB (%59.9) of 512 MB",
  "cloud":{
    "ZooKeeper":"localhost:9983",
    "liveNodes":"2",
    "collections":"1"}}
...

To stop Solr while running in SolrCloud mode, use the stop command, like this:

./bin/solr stop -all

Configure the Solr Connector for SolrCloud

There’s only one thing left to do: specify the client type as CLOUD in Liferay’s Solr connector.

  1. From System Settings or your OSGi configuration file, set the Client Type to CLOUD.

    clientType="CLOUD"

  2. Start Liferay if it’s not running already. If this is the first time starting after installing the Solr connector LPKG, follow the instructions in the log to restart Liferay again.

From the Solr System Settings entry, set the Client Type to Cloud.

Solr Connector Configuration Reference

Note

The Solr Connector properties apply equally to the Solr 7 and Solr 8 connectors. Substitue solr7 in the config file name (instead of solr8). In System Settings, see the entries starting with Solr 7.

Below are the default configurations along with settings that become available (in the System Settings Search category, or configurable by .config file) when you install the Solr connector application. These settings accept a limited set of values:

Configuration File: com.liferay.portal.search.solr8.configuration.SolrConfiguration.config
System Settings Entry: Solr 8

authenticationMode=["BASIC" or "CERT"]
clientType=["REPLICATED" or "CLOUD"]
defaultCollection="liferay"
logExceptionsOnly=B"true"
readURL="http://localhost:8983/solr/liferay"
writeURL="http://localhost:8983/solr/liferay"
zkHost="localhost:9983"

Configuration File: com.liferay.portal.search.solr8.configuration.SolrHttpClientFactoryConfiguration.config
System Settings Entry: Solr 8 HTTP Client Factory

basicAuthPassword="solr"
basicAuthUserName="solr"
defaultMaxConnectionsPerRoute="20"
maxTotalConnections="20"

Configuration File: com.liferay.portal.search.solr8.configuration.SolrSSLSocketFactoryConfiguration.config
System Settings Entry: Solr 8 SSL Factory

keyStorePassword="secret"
keyStorePath="classpath:/keystore.jks"
keyStoreType="JKS"
trustStorePassword="secret"
trustStorePath="classpath:/truststore.jks"
trustStoreType="JKS"
verifyServerCertificate=B"true"
verifyServerName=B"true"

Now you can configure Liferay for Solr and Solr for Liferay. Remember that Solr is deprecated. If you’re not constrained to use Solr or already a Solr expert, use Elasticsearch.

Not finding what you're looking for?

Pardon our dust as we revamp and transition our product documentation to this site. If something seems missing, please check Liferay Help Center documentation for Liferay DXP 7.2 and previous versions.

Try Liferay's Help Center