source: gs3-extensions/vishnu/trunk/README@ 26690

Vishnu package for ...

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

If you want to run it standalone:

You need to have Java 1.4 or higher and Ant installed. 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-api.jar.
These jar files all come as part of the Greenstone download. Some in gsdl3/lib/java, and servlet.jar in gsdl3/comms/jakarta/tomcat/lib (when unpacked).

Edit the build.xml file and change the prefix property to be the current directory.

Then run 'ant' (or "ant all').


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).

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