The Base Solr Install

In the first part of the Solr tutorial we will be looking at the very basics of getting a Solr instance up and running. This will be called the base install and will be used for every deployment that we are going to go through. This will also touch on source code management for the configuration files and ready deployment of other Solr installations.

so let's get going...

Ignorance is Bliss

The first thing you need to do is ignore all of the instructions that you may have read elsewhere, especially the 'Getting Started' information on the Solr site - whilst this is good and accurate it goes in far too deep, far too early (I should know, I have read almost every site/blog/wiki on the subject to no avail for the beginner.)

Solr Download

We will of course be needing a Solr installation so head on over to the mirror download location at http://www.apache.org/dyn/closer.cgi/lucene/solr/ and click on a mirror that is closest to you. I used the http://mirror1.smudge-it.co.uk/apache/lucene/solr/ mirror.

At the time of writing this tutorial, the page looked like the following:

Click on the 1.3.0 directory link and download the apache-solr-1.3.0.tgz (*NIX) or apache-solr-1.3.0.zip (Windows) link. For those of you who are too lazy or confused to work it out - click on this link to download the copy that I retrieved http://mirror1.smudge-it.co.uk/apache/lucene/solr/1.3.0/apache-solr-1.3.0.tgz.

The download is about 20.7Mb so it may take some time to come down fully. Once you have downloaded the file, you will not need to download it again.

Unzip the solr installation and you will have a directory listing along the following lines.

Whilst it is nice to jump straight into the examples and follow other tutorials - ignore this urge for the minute and keep on reading.

The files that we are interested in are:

The apache-solr-1.3.0.war file is the webapp that will be deployed to the tomcat server - more on this later.

The apache-solr-solrj-1.3.0.jar is of interest to us for our interaction with the solr server - more on interaction modes later in this tutorial.

The rest of the files (i.e *.xml and *.txt) are of interest for configuring the Solr server - we will delve into this quite deeply once we have the server set up.

Tomcat installation

The very first thing to do is to download a fresh copy of an Apache Tomcat server - here we will be using Tomcat 6.0.18 which can be downloaded here Tomcat 6.0.18. Please choose a the mirror that is closest to you - I used the 'core tar.gz' file.

If you are on windows you may wish to choose the '.zip' version rather than the '.tar.gz' that I chose. DO NOT download the 'Windows Service Installer' as we want to get into the nitty-gritty of starting the server ourselves and may conflict with other installations.

You may use any tomcat installation later than the one chose (6.0.18) and it won't really matter as this tutorial will age with time.

Now that you have downloaded the tomcat installation - you need to unzip/untar-gzip the file into a suitable location. Whilst the location is not important - I would recommend that you unzip it to an easily accessible place. Once the file has been unzipped, rename the directory from apache-tomcat-6.0.18 to tomcat-solr. Whilst this is not necessary, it makes it plain to see what the tomcat installation is for and won't create any conflicts with other tomcat installations.

On Mac OS X/*NIX I would place it in /java_servers/tomcat-solr/

On Windows I would place it in C:\java_servers\tomcat-solr\

IMPORTANT: No matter where the installation is placed, or on what operating system it is this will be referred to as the {BASE_TOMCAT_DIRECTORY}.

Looking at the Directory Structure

Taking a closer look at the Tomcat directory structure (i.e. {BASE_TOMCAT_DIRECTORY}) we can see the following files and sub-directories:

Note: the files are listed above in emphasised text to distinguish them from directories.

The two directories that we are interested in are the bin and webapps.

The webapps directory

Initially, the webapps directory contains the following files and sub-directories:

DELETE ALL of the directories so that it is empty.

The bin directory

This is where tomcat is started from and where we will place the solr configuration files. There are other ways to configure Solr, however this is the way that we are going to start.

Creating the Base Solr Install

At this point we are ready to merge both of the configurations together to get the solr server up and running.

Step 1: Copy and Rename the Web-Archive File

From the unzipped Solr directory - copy the file from dist/apache-solr-1.3.0.war to the {BASE_TOMCAT_DIRECTORY}/webapps/ directory AND rename the file to solr.war.

In my case I copied the /java_libraries/apache-solr-1.3.0/dist/apache-solr-1.3.0.war file to /java_servers/tomcat-solr/webapps/solr.war

Step 2: Create the Configuration Directories

create the following directories:

In my case I created:

Step 3: Copy The Configuration Files

Copy to following files to the /java_servers/tomcat-solr/bin/solr/conf/ directory.

Once again, for my installation I copied the following files /java_libraries/apache-solr-1.3.0/example/solr/conf/*.xml to /java_servers/tomcat-solr/bin/solr/conf/ and /java_libraries/apache-solr-1.3.0/example/solr/conf/*.txt to /java_servers/tomcat-solr/bin/solr/conf/.

IMPORTANT: The files that you just copied configure Solr for a completely different setup (the example setup) we will be over-writing these in the near future. The idea behind this is that this forms the base configuration for ANY Solr installation so it is good practice to know what you are doing.

The Base Installation Directory Listing

The tomcat directory listing should look identical to the following:

I have highlighted the directories and files of interest.

Congratulations

This is the {BASE_SOLR_INSTALL} which can be used over and over again. This contains everything you need to run a Solr instance. The only thing that needs to change is the files in the /java_servers/tomcat-solr/bin/solr/conf directory - which we will be looking at next (along with a simple example).

If you like, you can zip up the installation and unzip it when needed for a new Solr installation.