Getting Started

Notes: If you have already got everything up and running from the Quick Start - The 5 Steps section, then you can skip this section as this expands on that section and goes into finer-grained detail with deeper explanations.

If something is not working, see the When Something Goes Wrong section.


For this book we are going to be looking at a faceted search engine based on mechanical pencils - in particular 2mm clutch type mechanical pencils.[8] The data used is included with the Panl release package and offers a good learning opportunity to understand

  1. How to set up a Solr search server,
  2. How to index data,
  3. How to configure and run a Panl server, and
  4. What features are available through configuring the Panl server.

IMPORTANT: This is the Getting Started guide for Solr version 9, if you are using a previous version of Panl, ensure that you have the correct Panl release package and the you refer to the Setting up a Solr 7 or 8 server section in the Appendix for how to index data for those versions.

Downloading the Resources

Apart from a Java version 11 or greater, you will need the following resources

  1. Download the latest release of Synapticloop Panl - this book is using the solr-panl-9-1.2.0 version:
    https://github.com/synapticloop/panl/releases/
  2. Download the latest version of Apache Solr - this book is using the 9.6.1-slim version:
    https://solr.apache.org/downloads.html

Now unzip/untar/untgz the resources into an installation directory.  For my installation, I used the following:

The Solr server

On a Windows machine the installation directory was:
C:\java-servers\solr-9.6.1-slim\ 

whilst on a *NIX the installation directory was:
/Users/synapticloop/java-servers/solr-9.6.1-slim/ 

Whichever operating system that you are using, throughout this book, this directory is referred to as the SOLR_INSTALL_DIRECTORY.

The Panl server

On a Windows machine the installation directory was:
C:\java-servers\solr-panl-9-1.2.0\ 

whilst on a *NIX[9] the installation directory was:
/Users/synapticloop/java-servers/solr-panl-9-1.2.0/ 

Whichever operating system that you are using, throughout this book, this directory is referred to as the PANL_INSTALL_DIRECTORY.

Creating and Starting a Solr Cloud Instance

Run the following command which will start up Solr in cloud mode with default values i.e. two replicas and two shards per replica, with a default collection of 'gettingstarted'

Windows: 

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin\solr start -e cloud -noprompt


For example, the above command with the Windows installation directory replacement would translate to:

cd C:\java-servers\solr-9.6.1-slim\
bin\start -e cloud -noprompt

*NIX:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin/solr start -e cloud -noprompt

For example, the above command with the *NIX directory replacement would translate to:

cd /Users/synapticloop/java-servers/solr-9.6.1-slim
bin/start -e cloud -noprompt

This will start Solr in cloud mode with all of the defaults - you can check to see that it is up and running by going to the cloud admin console:

http://localhost:8983/solr/#/~cloud,

and you should be presented with a page similar to the following:



Image: The Solr Cloud Admin page

Notes: In the above image, under the 'Collections' column in the table, you will see the value 'gettingstarted' - this is the default collection that is set up and can be safely ignored.


The above shows the two cloud Solr nodes up and running - ignore the values for the moment - now it is time to create the mechanical pencil collection and index the data.

Notes: The Solr admin pages off a lot of information for troubleshooting collections and indexes.  It is worth your while getting to understand the functionality behind it, however it is beyond the scope of this book.

Creating a collection

To create a collection, we will be using the schema and data included in the Panl Server Package, which resides in the PANL_INSTALL_DIRECTORY/sample/solr/mechanical-pencils/ directory.

Run the following commands to create a new collection named mechanical-pencils


Windows:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin\solr create -c mechanical-pencils -d ↩
PANL_INSTALL_DIRECTORY\sample\solr\mechanical-pencils\ -s 2 -rf 2


*NIX:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin/solr create -c mechanical-pencils ↩
-d PANL_INSTALL_DIRECTORY/sample/solr/mechanical-pencils/ -s 2 -rf 2

This will create a collection called mechanical-pencils.  You can confirm the creation of the new collection on the cloud admin console: http://localhost:8983/solr/#/~cloud, and you should be presented with a page similar to the following:



Image: The Solr Cloud Admin page

Notes: In the above image, two collections are now shown, 'gettingstarted' and 'mechanical-pencils', you can safely ignore the 'gettingstarted' collection.

Indexing the Data

Now that the collection has been created, it is time to index the data.  Data for the mechanical-pencils collection is included in the Panl Server package in the PANL_INSTALL_DIRECTORY/sample/data/ directory.

To index the data:

Windows:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin\solr post -c mechanical-pencils ↩
PANL_INSTALL_DIRECTORY\sample\data\mechanical-pencils.json

*NIX:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin/solr post -c mechanical-pencils ↩

PANL_INSTALL_DIRECTORY/sample/data/mechanical-pencils.json

Starting The Panl Server

Windows:

Command(s)

cd PANL_INSTALL_DIRECTORY

bin\panl.bat -properties ↩
PANL_INSTALL_DIRECTORY\sample\panl\mechanical-properties\panl.properties


*NIX:

Command(s)

cd PANL_INSTALL_DIRECTORY

bin/panl -properties ↩  
PANL_INSTALL_DIRECTORY/sample/panl/mechanical-properties/panl.properties

http://localhost:8181/panl-results-viewer/

You will be presented with the following page:



Image: The In-Built Panl Results Viewer web app showing the list of available collection/FieldSet configurations

Select one of the collection/FieldSet URLs - for example

http://localhost:8181/panl-results-viewer/mechanical-pencils/firstfive

and start searching, sorting, faceting and sorting.

When Something Goes Wrong

Tips: Ensure that you have the latest version of this book. Whilst the commands shouldn't change, they might...

Alas, not everything always goes according to plan, when attempting to troubleshoot the instructions, the base advice is to check the logs and attempt to understand what the logging tells you, and if all else fails, start with a separate, clean Solr installation (as opposed to using an existing Solr installation) so that there are no errant configuration problems.

This will ensure that:

  1. All default ports are available for both the Solr (ports 8983, 7574, 9983) and Panl (port 8181) servers - which are referenced throughout this book, and
  2. No conflicting configuration is used from previous installations

Checking the Logs

The Solr web app has an in-built administration console which contains logging.  WHilst it can be confusing, it can give some hints as to what is happening and if there are any errors.

The Solr administration console can be viewed at:

http://localhost:8983/solr/#/~logging 



Image: The Solr Cloud Admin's logging page

Deleting a collection

Windows:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin\solr delete -c mechanical-pencils


*NIX:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin/solr delete -c mechanical-pencils


You will then need to re-create the collection, and re-index the data.


Restarting the Solr Panl tutorial process

  1. Stop all running Solr instances
    See the 'Stopping Solr' section below, make sure that you stop all instances, whether  it is for this process, or any other pre-existing installations that you may have
  2. Create separate Solr and Panl installations
    Re-download the installation files if necessary and unzip/un-tgz to a new, clean installation directory
  3. Re-run the tutorial, ensuring that you are using the correct values for
    SOLR_INSTALL_DIRECTORY, and
    PANL_INSTALL_DIRECTORY

Stopping Solr

Windows:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin\solr stop -all

*NIX:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin/solr stop -all

This will stop all instances of the Solr servers that are running in cloud mode.

IMPORTANT: If you have multiple Solr installations, you will need to make sure that you run the stop command from the Solr installation directory that it was started from.


Re-Starting Solr

Windows:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin\solr start -cloud -p 8983 -s "example\cloud\node1\solr"

bin\solr start -cloud -p 7574 -s "example\cloud\node2\solr" -z localhost:9983


*NIX:

Command(s)

cd SOLR_INSTALL_DIRECTORY

bin/solr start -cloud -p 8983 -s "example/cloud/node1/solr"

bin/solr start -cloud -p 7574 -s "example/cloud/node2/solr" -z localhost:9983


Worst-case scenario

If nothing else seems to work, delete the olr collection.

  1. Ensure that Solr is stopped,
  2. Delete the SOLR_INSTALL_DIRECTORY/example/cloud/node1, and
    SOLR_INSTALL_DIRECTORY/example/cloud/node2 directories (including all of their contents[10]).
  3. Re-create the Solr cloud instance,
  4. Re-create the collection(s), and
  5. Re-index the data

Next Steps

For indexing additional data, see the Additional Data section, for deeper understanding of how to set up a new collection and search page from scratch see the A Walkthrough  Example - The Book Store section.

~ ~ ~ * ~ ~ ~