Getting Started

This chapter goes into greater detail about the installation of both the Panl and Solr Servers, how to start the servers, index data in the Solr server instance, and run the Example Panl Results Viewer Web Application.

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.^[14] 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.

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-2.0.0 version:
   https://github.com/synapticloop/panl/releases/
2. Download the latest version of Apache Solr - this book is using the 9.8.0-slim version:
   https://solr.apache.org/downloads.html

Now unzip/untar/untgz the resources into an installation directory.  For the installation in this book, the following paths were used:

The Solr server

On a Windows machine the installation directory was:

C:\java-servers\solr-9.8.0-slim\ 

whilst on a *NIX^[15] the installation directory was:

/Users/synapticloop/java-servers/solr-9.8.0-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-2.0.0\ 

whilst on a *NIX the installation directory was:

/Users/synapticloop/java-servers/solr-panl-9-2.0.0/ 

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

Solr Versions Command Line Options

As the Solr server versions change, the command line options may also change.  Below is a table of command line options which need to be replaced if you are not using Solr version referenced in this book (i.e. Solr 9.8.0).

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: 

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

cd C:\java-servers\solr-9.8.0-slim\
bin\solr.cmd start -e cloud --no-prompt

*NIX:

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

cd /Users/synapticloop/java-servers/solr-9.8.0-slim
bin/solr start -e cloud --no-prompt

This will start Solr in cloud mode with 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

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.

Creating a collection

To create a collection, we will be using the schema and data included in the Panl server release 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:

*NIX:

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

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:

*NIX:

Starting The Panl Server

Windows:

*NIX:

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

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

To delete a collection, the Solr server must also be restarted, however in development mode, my preference is to delete all data and re-index.

Windows:

*NIX:

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

Stopping and 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:

*NIX:

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

Re-Starting Solr

Windows:

*NIX:

Worst-case scenario

If nothing else seems to work, delete the Solr 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^[16]).
3. Re-create the Solr cloud instance,
4. Re-create the collection(s), and
5. Re-index the data

Next Steps

1. For indexing additional data, see the Additional Data chapter, for a deeper understanding of how to set up a new collection and index data.  
2. Read the Solr Fundamentals and Panl Fundamentals sections for base information.
3. Work through setting up a search page from scratch with The Bookstore Walkthrough chapter.
4. Understand how to programmatically index a collection with the Filesystem Indexing And Searching Walkthrough chapter.

~ ~ ~ * ~ ~ ~