Installing and Configuring the Open SiteSearch Suite

Table of Contents

Introduction
Document Conventions
System Requirements
Preparing for the Installation
Planning Your Site Search Directory Structure
Gathering Installation Information
Configuring UNIX System Environment Variables
Configuring Windows NT/2000 System Environment Variables
SiteSearch Environment Ownership
Installing the SiteSearch Suite

Introduction

This document contains information about preparing to install the components that comprise Open SiteSearch Suite: the WebZ Extension, WebZ, and Database Builder. It also includes links to other documents with specific installation procedures for each SiteSearch component.

WARNING: This installation process does not "overwrite" an existing SiteSearch installation. To install and use version 4.1.0, 4.1.1, 4.1.2a, 4.2.0, or 4.2.0a to upgrade your existing installation, see the Product Updates page in the Documentation area of the Open SiteSearch Help Zone. The Web address for the Help Zone is http://sitesearch.oclc.org.

Document Conventions

• <WebZ_root> refers to the location of your SiteSearch (WebZ) environment.
• <version> refers to the SiteSearch version you are installing.
• <fullpath to JDK> is the location of your Java Development Kit (JDK)
• 4.1.x refers to SiteSearch 4.1.0 or 4.1.1.
• 4.2.x refers to SiteSearch 4.2.0, 4.2.0a, or 4.2.1.

For example:

• In UNIX, your root directory (<WebZ_root>) might be /web/netscape/ss_prod. In Windows NT/2000, your root directory might be j:\web\netscape\ss_prod.
• Your SiteSearch version might be version 4.1.1.
• The location of your JDK might be /usr/local/java/jdk1.1.4/bin.

SiteSearch System Requirements

For a list of hardware and software requirements, see OCLC SiteSearch Suite System Requirements. Install all prerequisite software necessary for SiteSearch before you install SiteSearch itself.

Preparing for the Installation

After installing supporting software, you can prepare to install the SiteSearch Suite components. Preparation involves:

• Planning your SiteSearch directory structure
• Gathering the system information you will need during installation
• Configuring environment variables for UNIX or Windows NT/2000

Planning Your SiteSearch Directory Structure

You need to establish the directory structure for your SiteSearch environment to ensure that you can install the software correctly on your host system. OCLC recommends either of the following directory structures, depending on the amount of disk space that you have available on your host system.

1. Create two SiteSearch environments in two separate directories: ss_prod and ss_test (either of which can be referred to as <WebZ_root>). In the ss_prod directory, install your Web server, WebZ Extension, and WebZ. You can use the ss_prod environment as the production environment for patron use to access Z39.50 and non-Z39.50 resources through a Web browser.
   
   In the ss_test directory, install your Web server, WebZ Extension, WebZ, and Database Builder (if applicable). You can use the ss_test environment as a test environment for your SiteSearch team to implement new interface elements, build local databases, test remote and local databases, and test server access before allowing patrons to use new resources. Once you test the changes in this environment, you can move the necessary configuration, HTML, database, and Java class files to the ss_prod environment, implementing the final changes for patron use without having to re-create or rebuild any elements in the production environment.
2. If you do not have enough available disk space for two separate environments, install all of the components that you have licensed into a single directory named sitesearch (which then becomes your <WebZ_root> directory).

Gathering Installation Information

You need to know the following information before you begin to install the Open SiteSearch suite:

• Root directory for each of the Open SiteSearch suite components (this is often <WebZ_root>).
• Type of Web server you will use.
• Port number where the Web server will host the WebZ software.
• Port number where the Web server will host Database Builder's Record Builder application (if applicable).
• Host operating system.
• Host system name (e.g., dove1.dev.oclc.org, atlanta.dev.oclc.org). The installer has a lookup feature that finds the default system name.
• Host system Internet Protocol (IP) address. The installer has a lookup feature that finds the default system IP address.
• E-mail address for the SiteSearch system administrator.
• SiteSearch system UNIX group or NT/2000 group with access rights to the files and directories in the directory where your Web server resides.
• User name for the SiteSearch system administrator.
• Location of the Perl interpreter on the host system.
• Location of the Java Development Kit (JDK) on the host system.
• Port number that the Hughes Technologies Pty. Ltd.'s Mini Structured Query Language (mSQL) server will run on.
• User name and e-mail address for the mSQL system administrator (if they differ from those of the SiteSearch system administrator).

Configuring UNIX System Environment Variables

Configuring the PATH variable for UNIX

The PATH variable defines the directories where UNIX must look to find executable files. To run SiteSearch and to install SiteSearch using the Java installers (if you wish), you must include the current directory, ".", and the path to your jdk/bin directory in your PATH variable, like the example shown below

    .:usr/local/java/jdk1.2.2/bin

Configuring the CLASSPATH variable for UNIX

The CLASSPATH environment variable defines which directories the JDK searches to locate Java classes. By modifying the CLASSPATH variable, you can install the Open SiteSearch suite using the Java InstallShield installer, add new Java classes to the software, and modify existing classes in the WebZ class packages. To do this, plan your directory structure for installation and set your CLASSPATH variable as follows:

    .:<fullpath to JDK>/lib/classes.zip: \
    <WebZ_root>/classes/ : \
    <WebZ_root>/classes/lib/SS<version>.jar: \
    <WebZ_root>/classes/lib/mail.jar: \
    <WebZ_root>/classes/lib/activation.jar

Important: You must also include the current directory, ".", in your CLASSPATH, if it doesn't already exist. Also, you need write permission in the directory in which you will run the Java installers.

Activating the New Settings

After you edit the PATH and CLASSPATH variables, log out of your UNIX session and log back in to activate the new settings.

Configuring NT/2000 System Environment Variables

Configuring the Path variable for NT/2000

The NT/2000 Path variable defines which directories NT/2000 searches to find executable files. You must modify your Path variable to run SiteSearch and to install the Open SiteSearch Suite using the Java installers.

Important: You must also include the current directory "." in your path, if it doesn't already exist. Be sure that you have the proper administration privileges for the NT/2000 server and write permissions for the directory in which you will run the Java installers.

Here are the directions for adding the JDK and your current directory to your NT/2000 Path variable.

Configuring the CLASSPATH variable for NT/2000

The CLASSPATH environment variable defines which directories the JDK searches to locate Java classes. By modifying the CLASSPATH variable, you will be able to install the Open SiteSearch suite using InstallShield, add new Java classes to the software, and modify existing classes in the WebZ class packages.

Once you install the WebZ Extension and WebZ, the installation procedure automatically edits the CLASSPATH to reference the WebZ classes, and the SiteSearch .jar file. When SiteSearch is installed without a CLASSPATH environment variable, the CLASSPATH should look similar to the example below, where X represents a drive letter.

    .;X:\<fullpath_to_JDK>\lib\classes.zip;X:\<WebZ_root>\classes; 
    X:\<WebZ_root>\classes\lib\SS<version>.jar; 
    X:\<WebZ_root>\classes\lib\mail.jar;
    X:\<WebZ_root>\classes\lib\activation.jar

You can examine the CLASSPATH variable in the Environment tab of the System settings in the Control Panel. Should you need to modify this variable manually, follow the steps shown for setting the Path variable, except to substitute CLASSPATH for Path in the procedure.

SiteSearch Environment Ownership

Ownership uniformity in your SiteSearch environment is critical for optimal performance.

The various SiteSearch components (such as JaSSI and ZBase) access various configuration files, HTML files, and Java classes while they operate. The processes created by these components must have the same ownership as the files they access.

System errors or erratic performance are likely to result if different processes have different owners. One common way for this to occur is when a SiteSearch environment is owned by one user and a different user subsequently starts the WebZ servers. Therefore, OCLC recommends that you:

• Install all SiteSearch software (WebZ Extension, WebZ, Database Builder) you have licensed, and any subsequent bug fixes, under the same user name (user account). In keeping with good UNIX system administration practices, we do not recommend that you use root as this user name in a UNIX environment.
• Ensure that all custom files you add to a SiteSearch environment have the same owner as the rest of the environment.
• Give every file in the SiteSearch environment the same new owner, should you need to change ownership of a SiteSearch environment.

Installing the SiteSearch Suite

Version 4.2.1

For SiteSearch 4.2.1, the second Open Source release, a single installer installs all SiteSearch components covered by the Open Source license. The document, Installing Open SiteSearch 4.2.1, describes the installation procedure.

Prior Versions

The following documents describe how to install the various components of the Open SiteSearch Suite. Install the SiteSearch components that you have licensed in the order in which they are listed below.

After you install all of the components that you have licensed, test the installation.

See Also

Testing the Open SiteSearch Suite Installation
Operating the WebZ System
Configuring the Access Component for WebZ (UNIX)
Configuring the Access Component for WebZ (Windows NT)