Installation Instructions

This document describes the installation process for the ASF distribution. This section contains the prerequisites that must be in place before installation can begin, an overview of the installation procedure, as well as a list of the components that will be installed.

Prerequisites

We require "free software" tools to be in place before the ASF software can be built. Following is a list of the prerequisite software:

GNU zip (gzip-1.2.4.tar.gz)
GNU Make (make-3.76.1.tar.gz)
GCC the GNU C Compiler (gcc-2.8.1.tar.gz) including g++
GNU C++ runtime library (libg++-2.8.1.1a.tar.gz)
perl (v5.004.04 is required for the perl-based crawler w3mir)

Go here for information on how to get these products.

Installation Procedure Overview

Get the ASF distribution
Build the ASF distribution
(Optional) Test the ASF distribution with the demo setup
(Optional) Copy the ASF files to preferred site-specific locations
Build database(s) to search
Configure ASFserv
Start ASFserv
Verify Installation

Components

The ASF Basic distribution includes source code for its two main components - Isearch and ASFserv. During the installation procedure, the source code is compiled into executable programs. These programs and there function are listed below:

Programs:

Iindex: Iindex indexes text files and creates a searchable, full-text and field-based database.
Isearch: Isearch is a command line utility program to search the databases created by Iindex. The Isearch command line utility is usually used in ASF only for verifying the successful creation of a database. The Isearch search engine functionality is obtained through the use of the Isearch library routines.
Iutil: Iutil is a command line utility program to manipulate the databases created by Iindex. Used in ASF to create skeleton GILS records in XML for each document in the index.
ASFserv: ASFserv is a Z39.50-compliant server which can process searches against databases created by Iindex and return documents.

In addition to the executable programs, the ASF Basic distribution includes libraries that are used by the executable programs. These programs and there function are listed below:

Libraries:

Isearch: Search and retrieval routines, used by Iindex and ASFserv
libemerge: Utility routines used by ASFserv and Search API
eutil: Utility routines used by ASFserv and Search API
sai: Search API routines
Yaz: Z39.50 protocol implementation, used by ASFserv

Installation Procedure

This section contains the complete installation procedure for the ASF distribution. A separate section exists for each of the main installation steps shown in the Installation Overview.

Get the ASF distribution

The ASF Distribution is only available currently via FTP. You can use your favorite FTP client to retrieve the ASF Basic distribution from the ASF site - asf.gils.net, in /pub/asf directory (or from ntiaunix2.ntia.doc.gov,in the pub/asf/current/) and store it in a convenient place (e.g. the /home/asf directory). Or, if your web browser is FTP-capable, click on the following location: ftp://ftp.asf.gils.net/pub/asf/

Note: The rest of the installation procedure assumes that you have saved the ASF basic distribution in a directory called /home/asf. If this is not the case, simply replace any occurrences of /home/asf with your chosen directory.

Build the ASF distribution

In this step, you will unpack the ASF distribution and build all of the executables. You should end up with a directory structure that looks like the following:

asf/ -------+
            |
            +- bin/
            |
            +- cgi-bin/
            |
            +- conf/
            |
            +- crawls/
            |
            +- dbs/
            |
            +- doc/ ----+
            |           |
            |           +- html
            |           |
            |           +- man
            |           |
            |           +- sgml
            |
            +- files/
            |
            +- htdocs/
            |           |
            |           +- Isearch
            |           |
            |           +- community
            |           |
            |           +- database
            |           |
            |           +- doc
            |           |
            |           +- files
            |           |
            |           +- help
            |           |
            |           +- includes
            |           |
            |           +- maintenance
            |           |
            |           +- nodes
            |
            +- icons/
            |
            +- logs/
            |
            +- sample_data/
            |
            +- src/ ----+
                        |
                        +- search_engines -+
                        |                  |
                        |                  +- Isearch
                        |
                        +- subsystems -----+
                        |                  |
                        |                  +- ASFadmin
                        |                  |
                        |                  +- ASFserv
                        |                  |
                        |                  +- apache
                        |                  |
                        |                  +- htdig
                        |                  |
                        |                  +- ids
                        |                  |
                        |                  +- pavuk
                        |                  |
                        |                  +- zap
                        |
                        +- utils ----------+
                                           |
                                           +- eutil
                                           |
                                           +- libemerge
                                           |
                                           +- sai
                                           |
                                           +- yaz

To create this directory structure, execute the following commands (from the /home/asf directory):

gunzip asf-*.tgz
tar xvf asf-*.tar
cd asf
make linux (or solaris, if that's what OS you have)

Perform initial setup

bin/asf_setup

Start by taking the defaults to run the software from the distribution directory. In certain cases (for example, if you are building the installation as root), protections may need to be changed to allow the administrative interface to write to the file system. You can either change ownershop of the asf/ directory tree to match the owner of the http process (the default is "nobody"), or rerun asf_setup to run the server as the owner of the asf/ directory tree. Under no circumstances should you run the http server as root - this would open potential security problems.

Start ASF servers

bin/start_main_servers

Point web browser at administration server

"http://yourhost:port"

The administrative interface will let you proceed using HTML forms. You can build local and remote databases and perform searches.