source: trunk/greenstone3-extensions/vishnu/README@ 8405

Vishnu package for ...

LINUX INSTALL:

If you are running this as part of Greenstone, just installing Greenstone will install Vishnu.

If you want to run it standalone:

The environment variable JAVA_HOME needs to be set.
You need to have MG installed - this should be the version from Greenstone, and you need the mg.jar file in your CLASSPATH and the libmgjni.so in your LD_LIBRARY_PATH.
You need the lucene 1.4 or higher jar file in your CLASSPATH.
Other jar files needed in CLASSPATH: xercesImpl.jar, servlet.jar.

Edit the src/vishnu Makefile and uncomment the prefix for stand-alone vishnu.

Then run the following:

make
make install

WINDOWS INSTALL:

Doesn't work on windows yet.

COLLECTION BUILDING:

Make a directory called collections inside the main vishnu directory. Inside this, create a new directory for your collection. The name of this directory is the collection identifier. Inside the collection directory create a new direcotry called import. Inside here put all the documents that you want in your collection. Documents must be plain text, xml or html.

Then you can build the collection:

Command line: 
java vishnu.builder.CollectionBuilder -collsHome (directory where collections live: path-to-vishnu/collections) -collection (directory name of collection) -name (descriptive name for collection) -description (collection description) -index ("mg" or "luc")

If you want to use views, add the option "-use-views" to the above command. This will create a separate index for each sub-directory in the import folder, and you can search each sub-view independently.

Using a GUI tool:
java vishnu.builder.IndexerGUI

Fill in the fields as appropriate, and click "Start indexing".

Once the collection is built, you need to rename the building directory to index. Collections are built into the building directory, but served from the index directory. This allows you to serve a built collection while rebuilding.

For collections in the Greenstone 3 context, you will need to create the files etc/collectionConfig.xml and index/buildConfig.xml.
These should look like the following:

etc/collectionConfig.xml:
<collectionConfig>
  <metadataList>
    <metadata name="creator">creator's email address</metadata>
  </metadataList>
  <displayItemList>
    <displayItem name='name' lang='en'>Collection name</displayItem>
    <displayItem name='description' lang='en'>Collection description
    </displayItem>
  </displayItemList>
</collectionConfig>

index/buildConfig.xml:
<buildConfig>
  <metadataList/>
  <serviceRackList>
    <serviceRack name="Visualizer">
      <engineType name="MG"/> <!-- or LUCENE, depending on how you built the collection -->
    </serviceRack>
  </serviceRackList>
</buildConfig>

Note that you cannot use views in the Greenstone context yet.

RUNNING THE SERVLET:


If you are running this standalone, you need to run a servlet container for VisServlet.
We have provided an example configuration for use with Tomcat (version 4.1).

Set the prefix in the src/vishnu Makefile to be ../.., then the servlet class and jar files will be installed in the correct places.
The vishnu/web directory is setup to be the context directory for vishnu in Tomcat. 
You need to edit Tomcat's conf/server.xml file, and add in the context for vishnu. Add the following element after the tomcat root context element:

<Context path="/vishnu" docBase="full-path-to-vishnu/web" debug="1" reloadable="true"><Resources allowLinking='true'/></Context>
(replacing "full path-to-vishnu" with the path to the vishnu directory.)
Edit the vishnu/web/WEB-INF/web.xml file and put in the correct path to your collections directory.

The vishnu.jar file needs to be in your CLASSPATH, and make sure that Tomcat is using your CLASSPATH.

RUNNING THE APPLET:

The file vishnu/web/index.html is an introductory page about vishnu, and contains the applet. Make sure that the library parameter has the correct address for your visualiser servlet. The default is http://localhost:8080/vishnu/server. This will be correct if you have installed Tomcat to use port 8080, and have set the vishnu servlet up as described above. But note, if you are using Mozilla, it may not like localhost here, so if you have problems, try putting the full name of the server running Tomcat in place of localhost.

If you are running Tomcat as described above, you can view this index file at http://localhost:8080/vishnu/index.html