Installing and Configuring Sphinx

Sphinx is an important component of the Locum library. It is well worth your time to read through the Sphinx documentation because you will be able to greatly customize it to exactly match your needs. Of course, Locum is distributed with a Sphinx configuration file that should work out of the box with very little modification.

Locum was designed to run on Sphinx 0.9.8, which can be downloaded here.

Also, make sure the following are installed on your system (package names may vary by Linux distribution. For more detailed information on these prerequisites, see the Sphinx home page):

• g++
• libg++
• make
• libmysql++-dev

Here are the recommended steps to get Sphinx installed (run as root):

cd ~
wget http://sphinxsearch.com/downloads/sphinx-0.9.8.tar.gz
tar zxvf sphinx-0.9.8.tar.gz
cd sphinx-0.9.8
./configure --prefix=/usr/local/sphinx
make
make install


Next, we'll make sure that the PHP API is available in the install tree. From the same source directory do:

mkdir /usr/local/sphinx/lib
cp api/sphinxapi.php /usr/local/sphinx/lib/


Next, you have to create a sphinx user, a PID directory and set the right ownership so we can install a nice init script ( !!! make sure you do '>>' and NOT '>'):

echo "sphinx:x:999:999:Sphinx User,,,:/usr/local/sphinx/:/bin/true" >> /etc/passwd
echo "sphinx:x:999:999:Sphinx User,,,:/usr/local/sphinx/:/bin/true" >> /etc/passwd-
echo "sphinx:x:999:" >> /etc/group
echo "sphinx:x:999:" >> /etc/group-
mkdir /usr/local/sphinx/var/run
chown -R sphinx.sphinx /usr/local/sphinx/var
cd /etc/init.d
wget http://www.thesocialopac.net/sites/thesocialopac.net/files/sphinx
chmod +x /etc/init.d/sphinx


Finally, you're going to copy the Locum-specific Sphinx configuration file into place.

cp /usr/local/lib/locum/sphinx/sphinx.conf /usr/local/sphinx/etc/


Once that's copied over, edit it, and replace all instances of "locum_db_user" and "locum_db_pass" with the MySQL username and password you set up in the initial preparation.

Sphinx should now be ready. We will do a little more with it when we get in to installing Locum.

Installing Insurge

For the purposes of running SOPAC, you will be concerned only with the Insurge client component.

This installation guide covers a stand-alone installation of Insurge. Future documentation will describe the process involved in participating with a central social repository. In this context, installation of Insurge is very simple.

First, you must install the Insurge database schema:

mysql -u root -p < /usr/local/lib/insurge/sql/scas_insurge.sql

If you did not name your database 'scas', you will need to edit the schema file to reflect that.

If the schema was successfully imported, then you can move on to configuring Insurge. Insurge's configuration options are located in its INI file: /usr/local/lib/insurge/config/insurge.ini.

Because we are setting up a stand-alone (non-repository) Insurge site, you only need to set the dsn_file parameter. It should look something like:

dsn_file = "/usr/local/etc/scas_dsn.php"


Installing Locum

Setup of Locum is probably the most complex step in this installation process. This is because Locum must be configured to operate in your environment. Since every library is different, the actual organization and structure of configuration files can vary significantly between institutions.

What you will need

• A list of material codes and their names
• A list of location codes and their names
• Your Amazon API access key (optional)
• Your Syndetics customer ID token (optional)

Installation

First, you must install the Locum database schema:

mysql -u root -p < /usr/local/lib/locum/sql/scas_locum.sql

If you did not name your database 'scas', you will need to edit the schema file to reflect that.

Once you've verified that the schema has successfully imported, you will need to configure MySQL to initialize the Locum facet heap table. In your /etc/mysql/my.cnf (may be in a different location, depending on your distribution), add the following under the [mysqld] section:

max_heap_table_size = 200M
init_file = /usr/local/lib/locum/sql/locum_init.sql


Once you've done this, you can move on to configuring Locum. Locum's configuration options are located in its INI file: /usr/local/lib/locum/config/locum.ini.

Take some time to become familiar with the distributed INI file. Many of the options are self-explanatory, but several critical options may need some explanation.

The initial configuration section is fairly straight-forward. Be sure to create /usr/local/var/log if it does not exist. run_quiet forces locum to only use the log file and not stdout as well.

[locum_config]
dsn_file = "/usr/local/etc/scas_dsn.php"
log_file = "/usr/local/var/log/locum.log"
run_quiet = FALSE


You should not have to change these values if you installed Sphinx using this guide.

[sphinx_config]
api_path = "/usr/local/sphinx/lib"
server_addr = "localhost"
server_port = 3312


If you have pcntl enabled in PHP, you should not need to change this. You may want to come back and tweak it later. If you do not have pcntl enabled, you'll need to change harvest_with_children to FALSE. Your harvest time will be much greater without it, however.

[harvest_config]
harvest_with_children = TRUE
max_children = 10
harvest_reach = 1000


Setting up your API configuration is entirely optional. But you will need to enable either Syndetics or Amazon if you want to have cover images. Also, Locum uses Google for search suggestions. You can enable this here and tell Locum the number of search result under which to activate it. In this example here, Locum will try Syndetics for a cover image first, then Amazon.

[api_config]
use_amazon_images = TRUE
amazon_access_key = "786YBG8D7F6GO8DFN7B6"
amazon_img_prio = 2
use_syndetic_images = TRUE
syndetic_custid = "syndtid"
syndetic_img_prio = 1
use_google_suggest = TRUE
suggestion_threshold = 10


This section is critical in order for Locum to integrate with your ILS. It is where you determine which ILS connector to use and how to connect to your ILS server. Because this example uses the III connector, it will need to harvest on port 2082 (using xrecord). You will need to make sure the harvesting server has access to that port on your ILS server and that if there is a firewall between, it can pass through it.

[ils_config]
ils = "iii";
ils_version = "2006"
ils_server = "ils.yourlibrary.org"
ils_harvest_port = "2082"


The rest of the configuration file will be very specific to your organization. Read the commented sections carefully for instructions. Bear in mind that for purposes of the initial harvest, any sections below [ils_config] do not need to be completed yet. It is safe to "tweak them" once everything is up and running.

Installing SOPAC

Because SOPAC is a Drupal module, installation paths will vary from system to system. You will install and enable it as you would with any other third party Drupal module.

A note on SSL

It is strongly recommended that you purchase a SSL certificate for your Drupal site. SOPAC has the built-in ability to encrypt pages appropriately and will take advantage of your encrypted server.

Configuring Apache2 for SSL support is beyond the scope of this guide and there is plenty of instruction and support available on the web.

You will, however, need to make the following addition to your SSL virtualhost definition (just the SSL definition, not the regular one). Your enabled SSL site should be encapsulated in a definition that looks like this:

<VirtualHost 1.2.3.4:443>
...
<VirtualHost>


Within that definition, put the following line:

SetEnv HTTPS TRUE


SOPAC/SSL integration will not work unless this parameter has been properly set.

Configuring SOPAC

Once you have succesfully installed the SOPAC module, you will want to tailor it to your environment. SOPAC makes this very easy for you.

First you will need to set the appropriate permissions. They should look something like this:

Next, visit the SOPAC configuration page under Administer > Site configuration > SOPAC Settings (or /admin/settings/sopac). You'll notice that there are three configuration sections. The first contains the critical elements that must be correctly set:

You can choose to tweak the settings in the other two sections now, or wait until later.