Table of Contents

Installation / Quick Start
Install Run-Time Environment
Install the XTF Package
Verify that the Servlets are Correctly Installed
Install the Sample Document Library
Verify that Document Retrieval Works
Index the Sample Document Library
Verify that Document Searching (crossQuery Servlet) Works
Done
[ You are here: XTF -> Deployment Guide -> Installation / Quick Start ]

Installation / Quick Start

This section provides simplified instructions for installing and configuring an XTF system. By using the pre-created document library, configuration files, and file system tree, this section yields a running XTF system with minimal effort. Be sure to go through the sub-sections in the order they appear, as each new section builds on the previous ones.

Install Run-Time Environment

The XTF servlets and tools depend upon a run-time environment consisting of the following:
If you need help installing these run-time tools, follow the steps outlined in the Run-Time Environment Installation/Configuration section.

Install the XTF Package

Installing the XTF Package usually consists of these simple steps:
  1. Download the latest XTF package (xtf-2.x.war) from SourceForge.
  2. Very important: rename the file to xtf.war, so that the servlet container will unpack it to the xtf subdirectory (instead of xtf-2.x).
  3. Place the xtf.war file (not xtf-2.x.war) inside the webapps directory of the servlet container (e.g. Tomcat or Resin).
  4. Browse to a URL referencing one of XTF servlets (such as the one below). The servlet container should unpack the archive for you, creating an xtf sub-directory within webapps. In rare cases, you may need to restart the servlet container to get it to recognize the new application.

Verify that the Servlets are Correctly Installed

To verify that the servlets are running,, bring up your web browser and enter the following URL:
http://localhost:8080/xtf/search
(Note: This URL assumes you're running the browser on the same machine as XTF, and that the servlet container is configured to listen to port 8080. If not, substitute your server name and/or port for "localhost:8080").

Accessing this URL should bring up an error page exactly like the following screen-shot (not that the error is expected at this point):
SearchQueryGenErr.gif

Receiving this error page indicates that the crossQuery servlet is running; it's okay at this point that it can't access the index. Simply accessing this URL causes the servlet container to unpack the web archive file, creating an xtf sub-directory below the container's webapps directory, which in turn automatically installs the crossQuery and dynaXML servlets, the textIndexer tool, and a sample configuration that allows you to work with the default Sample Document Library. The reason we get an error is that we haven't installed and indexed the Sample Document Library yet.

If you get any other type of error, including File Not Found or Page Not Found, then XTF is not properly installed, and you should go back and double-check that you have correctly performed the steps described in the previous section.

Install the Sample Document Library

Once the crossQuery servlet is up and running, its time to install the sample document library. To do so, perform the following steps:
  1. Download the sample package (sample-data-2.x.zip) from SourceForge.
  2. Using your favorite ZIP file utility, extract the sample document library's data directory and move it into into your XTF directory: servlet-container-directory/webapps/xtf.
  3. You should now have the following directory present (among others): servlet-container-directory/webapps/xtf/data/tei/ft958009mm. This directory contains the document we will attempt to display.

Verify that Document Retrieval Works

Once the Sample Document Library has been installed, you can verify that basic document retrieval works. To do so, bring up your web browser and enter the following URL:
http://localhost:8080/xtf/view?docId=tei/ft958009mm/ft958009mm.xml
Doing so should bring up the cover for the book The Opening of the Apartheid Mind, looking like this (without the query highlighting -- we'll get to that soon):

ViewPage.png

Index the Sample Document Library

Before you can verify that basic document searching works, you need to index the document library. To do this, follow the steps below. (Note: this procedure depends on a Unix-type shell and a Perl command interpreter. If you are running XTF on Microsoft Windows, please see the section Running on Windows.)
  1. Switch to the bin sub-directory under the XTF installation directory:
    $ cd servlet-container-directory/webapps/xtf/bin
  2. Once in the bin sub-directory, make the textIndexer script runnable, then run it:
    $ chmod +x textIndexer
    $ ./textIndexer -index default
The textIndexer tool will now index the document library that you downloaded earlier. This should only take a couple of minutes, and you'll see output something like this:
TextIndexer v2.x
 
  Purging Incomplete Documents From Indexes:
  Done.
 
  Indexing New/Updated Documents:
    Index: "default"
      Scanning Data Directories....
      (5%)   Indexing [ead/bell/bell.xml] ... (1 stored key) ... Done.
      (6%)   Indexing [ead/clay/clay.xml] ... (1 stored key) ... Done.
      ...
    Done.
  Done.
 
  Optimizing Index:
    Index: [/Users/mhaye/Software/tomcat/webapps/xtf/index/] ... Done.
  Done.
 
  Updating Spellcheck Dictionary:
    ...
  Done.
 
Total time: 1 minute, 8 seconds.
Indexing complete.

Verify that Document Searching (crossQuery Servlet) Works

Once the document library has been indexed, you can verify that basic document searching using the crossQuery servlet works. To do this, bring up your web browser and enter the following URL:
http://localhost:8080/xtf/search
Doing so should bring up a page where you can enter information to search for, like this:
SearchPage.png
Entering the word africa in the keyword field and pressing the Search button should yield a list of matching documents that looks like this:
SearchResult.png
Note that the first document listed is the book entitled The Opening of the Apartheid Mind, which we selected manually in our initial test of the document retrieval (dynaXML) servlet. Clicking on the book title effectively passes a URL to the dynaXML servlet that looks like the one we entered manually before, and will result in the cover page for the book being shown. In contrast, clicking on the word africa in the search result blurbs will take you to the actual place in the book where the word "africa" appears.

Done

You're ready to start adding data to and/or customizing XTF. To add data in one of the formats already supported, simply put it into the data directory and re-run the textIndexer tool. To make the sample installation better suit your needs, continue with one of the following sections: Configuring the textIndexer Tool, Configuring the dynaXML Servlet, and Configuring the crossQuery Servlet.