Apache Solr is an open source search engine suitable for enterprise use and built on Apache Lucene. This quick tutorial shows how to install and run Apache Solr on Liberty.

The tutorial walks through the steps for downloading both Apache Solr and Liberty, installing the Solr web application on Liberty, populating Solr with data, and finally querying the data via the Solr web app.

Apache Solr is built on Apache Lucene, the open source full-text indexing and search engine. Solr provides extensions to Lucene for enterprise-level service, such as scalability and distributed indexing, along with an easy-to-use web application that provides RESTful services for administration and search. This tutorial uses Solr 4.10.0.

The tutorial is broken down into 5 steps:

  1. Download and install Liberty and Solr
  2. Install the Solr web application on Liberty
  3. Verify Solr is up and running
  4. Populate Solr with data
  5. Query Solr

Step 1: Download and install Liberty and Solr

Download the latest version of Solr and extract it anywhere on your machine. For the remainder of this tutorial, {solr.install.dir} refers to the Solr installation directory.

Download the latest GA release of Liberty via Eclipse or as just the Liberty Runtime, or download the latest Liberty beta. Run the self-extracting archive anywhere on your machine.

Step 2. Install Apache Solr on WebSphere Liberty

First things first, create a Liberty server for hosting the Solr web application. The Liberty server must have (at a minimum) servlet-3.0 installed and should have an httpEndpoint defined in the server.xml of the Liberty server:


    <httpEndpoint id="defaultHttpEndpoint"
                  httpsPort="9443" />


The Solr web app can be found at {solr.install.dir}/example/webapps/solr.war. To install it in Liberty, simply configure an <application> element that references the WAR file. We also must configure an external library reference for the application, since solr.war depends on a handful of jars located in {solr.install.dir}/example/lib/ext. For example:

    <application location="{solr.install.dir}/example/webapps/solr.war">
        <privateLibrary id="solrExt">
          <fileset dir="{solr.install.dir}/example/lib/ext" includes="*.jar"></fileset>


Finally, we need to tell solr.war where to find the Solr home directory (where the indexed data live). Do this by setting the Java system property solr.solr.home. The Solr installation comes with an example Solr core at {solr.install.dir}/example/solr. Configure the system properties in Liberty in the jvm.options file for the Liberty server:



That’s it! Now go ahead and start (or restart) your Liberty server (a restart is necessary to pick up the changes to jvm.options).

Step 3. Verify Solr is up and running

You can verify the Solr app is running by bringing up the Solr administrative console, which by default is hosted under the /solr web context root. Assuming your server is configured for localhost:9080, open http://localhost:9080/solr in a browser.

If all is well you should see something like this:


If you get a 404 or a Solr error message, check Liberty’s server logs for more information.

Step 4. Load documents into Solr

Before we can query Solr we have to load it up with sample data. There are a number of sample documents in directory {solr.install.dir}/example/exampledocs. We’ll use the documents listed in file books.json:

        "id" : "978-0641723445",
        "cat" : ["book","hardcover"],
        "name" : "The Lightning Thief",
        "author" : "Rick Riordan",
        "series_t" : "Percy Jackson and the Olympians",
        "sequence_i" : 1,
        "genre_s" : "fantasy",
        "inStock" : true,
        "price" : 12.50,
        "pages_i" : 384
        "id" : "978-1423103349",
        "cat" : ["book","paperback"],
        "name" : "The Sea of Monsters",
        "author" : "Rick Riordan",
        "series_t" : "Percy Jackson and the Olympians",
        "sequence_i" : 2,
        "genre_s" : "fantasy",
        "inStock" : true,
        "price" : 6.49,
        "pages_i" : 304
        "id" : "978-1857995879",
        "cat" : ["book","paperback"],
        "name" : "Sophie's World : The Greek Philosophers",
        "author" : "Jostein Gaarder",
        "sequence_i" : 1,
        "genre_s" : "fantasy",
        "inStock" : true,
        "price" : 3.07,
        "pages_i" : 64
        "id" : "978-1933988177",
        "cat" : ["book","paperback"],
        "name" : "Lucene in Action, Second Edition",
        "author" : "Michael McCandless",
        "sequence_i" : 1,
        "genre_s" : "IT",
        "inStock" : true,
        "price" : 30.50,
        "pages_i" : 475

As you can see, books.json contains four documents. A Solr document consists of name-value fields. The metadata for these fields are defined to Solr in a file named schema.xml. The metadata informs Solr how to process each field (for example, whether or not the field should be indexed). Each document collection in Solr has its own schema.xml.

For this tutorial we will use the example collection, collection1, whose schema is located at {solr.install.dir}/example/solr/collection1/conf/schema.xml. The default schema for collection1 has field definitions for all of the fields listed in books.json.

Solr schema configuration is a complex topic that goes beyond the scope of this tutorial. For more information, see the Solr documentation.

There are a number of ways to load documents into Solr. If you have curl or some other handy command-line web client, you can POST the JSON documents directly to Solr’s RESTful API:

    curl 'http://localhost:9080/solr/collection1/update/json?commit=true' 
         --data-binary @{solr.install.dir}/example/exampledocs/books.json 
         -H 'Content-type:application/json'


Or you can post them through the form provided by the Solr administrative console at http://localhost:9080/solr/#/collection1/documents.


Just copy and paste the JSON documents into the Document(s) field.

The only drawback to this approach is that you’ll have to submit the documents one at a time. The form cannot handle a JSON array.

Step 5: Query Solr

Now that we’ve loaded documents into Solr, we can query for them. The Solr app provides a query form located at http://localhost:9080/solr/#/collection1/query.


Type your search terms in the field labeled q. Typically a Solr search takes on the form {field}:{search-term} where {field} is the document field to search. If you don’t specify a field, by default it will search the text field.

The text field, by default, contains data copied from several fields, including the fields cat, name, and author from the books.json sample data above. All of these default values are specifically configured for collection1 in its schema.xml; they are not Solr-wide defaults.

For example, if you search for just “greek” (no field), you should get back a single result:


If you try to search just percy, you’ll get zero results, even though two books have the word percy in their series_t field. This is because the series_t field is not copied to the default text field. Instead search for series_t:percy, and you’ll get two hits, as expected.

Further Reading

The purpose of this tutorial is to get you up and running with Solr on Liberty as quickly as possible. Solr has extensive capabilities in the areas of loading documents, indexing, and querying that are not covered here as they go well beyond the scope of this tutorial.

For more information about Solr, check out Solr’s resource page.

For more information about Liberty, check out the v855 knowledge center.

2 comments on"Running Apache Solr on WebSphere Liberty"

  1. Manas Ranjan Behera April 01, 2019

    After solr 5 there is no war file to configure in the liberty server. Is there a specific way to install solr 5 or beyond that in liberty server. kindly help me to install solr 8 on liberty server.

  2. Did you try to enable SOLR jmx mbeans for performance metrics in Liberty?
    I failed to do so. The SOLR jmx mbeans is enabled by default. Refer: http://wiki.apache.org/solr/SolrJmx. I can see the solr mbeans when deployed to Tomcat with JConsole. But when deployed to Liberty, I didn’t see the solr mbeans, only Liberty mbeans listed.

    Do you have any idea for this problem?

Join The Discussion

Your email address will not be published. Required fields are marked *