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:
Create a configuration file named
com.liferay.portal.bundle.blacklist.internal.BundleBlacklistConfiguration.config
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"\ ]
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,
Navigate to Control Panel → Apps → App Manager.
Once in the App Manager, search for elasticsearch. Find the Liferay Connector to Elasticsearch 6/7 modules and open the 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,
Enter
lb -s | grep 'search' | grep 'elasticsearch|tuning'
You’ll see several active bundles for the connector to Elasticsearch and the search tuning modules.
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.
Liferay CE:
Liferay DXP:
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:
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:
Liferay 7.1-7.3: Solr 8.6.3
Liferay 7.1-7.2: Solr 7.5.0
Navigate to Solr Home (
solr-[version]/server/solr
) and create a new folder calledliferay
.Create two new subfolders:
liferay/conf
andliferay/data
.Copy the contents of
Solr_Home/configsets/_default/conf
toSolr_Home/liferay/conf
.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 extractMETA-INF/resources/solrconfig.xml
and
META-INF/resources/schema.xml
to
Solr_Home/liferay/conf
This replaces the current
solrconfig.xml
andschema.xml
files with ones that tell Solr how to index data coming from Liferay.Create a
core.properties
file inSolr_Home/liferay
and add this configuration:config=solrconfig.xml dataDir=data name=liferay schema=schema.xml
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
Start the Solr server by entering the following from the top-level folder of your Solr installation (
solr-[version]
):./bin/solr start -f
The Solr server listens on port
8983
by default. Navigate to http://localhost:8983/solr/#/~cores (assuming you’re testing locally withlocalhost
as your host), and confirm that theliferay
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:
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.
Once the app LPKG is downloaded, copy it to
Liferay_Home/osgi/marketplace
and put any configuration files inLiferay_Home/osgi/configs
.Start Liferay.
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.
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.
Stop the Solr server if it’s running.
Navigate to the
Solr_Home/configsets
folder and create a folder calledliferay_configs
Copy the
conf
folder fromSolr_Home/liferay
to theliferay_configs
folder you just created.The
configset/liferay_configs
folder contains the SolrCloud Liferay collection configuration and is uploaded to ZooKeeper. When you copy theconf
folder from theliferay
server configured earlier, you use theschema.xml
andsolrconfig.xml
files provided with the Liferay Solr Adapter.Launch an interactive SolrCloud session to configure your SolrCloud cluster:
./bin/solr -e cloud
Complete the setup wizard. These steps demonstrate creating a two-node cluster:
Enter
2
for the number of nodes.Specify ports
8983
and7574
(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.
From System Settings or your OSGi configuration file, set the Client Type to CLOUD.
clientType="CLOUD"
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.
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.