source: trunk/gsdl3/README.txt@ 9892

Greenstone 3 (GSDL3)
Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato
GSDL3 comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt
This is free software, and you are welcome to redistribute it

Installing Greenstone from a binary distribution (Linux):
---------------------------------------------------------

Download the gsdl3-x.xx-linux executable file, and run it. Follow the instructions given.

Installing Greenstone from a binary distribution (Windows):
-----------------------------------------------------------

Download the gsdl3-x.xx-win32.exe executable file, and double click on it. 
Follow the instructions given. 


Installing Greenstone from a CVS checkout (Linux and Windows):
--------------------------------------------------------------

Checkout the code:

cvs -d :pserver:[email protected]:2402/usr/local/global-cvs/gsdl-src co gsdl3

Build and install:

Greenstone is built and installed using Ant (Apache's Java based build tool, 
http://ant.apache.org). You will need a Java Development 
Environment (1.4 or higher), and Ant installed to use Greenstone. You can download Ant from http://ant.apache.org/bindownload.cgi.

In the gsdl3 directory, you can run 'ant' which will give you a help message.
Running 'ant -projecthelp' gives a list of the targets that you can run - these
do various things like compile the source code, startup the server etc.

For a first time install, run 'ant install'.

The file build.properties contains various parameters that can be set by the user. Please check these settings before running 'ant install'.
Greenstone 3 uses some parts of Greenstone 2 for collection building using the Librarian Interface. It downloads the relevant parts during install. If you have Greenstone 2 already installed, please set the gsdl2.installed.path property to be the root of your Greenstone 2 installation. Greenstone 3 will then use this installation rather than downloading the extra Greenstone 2 bits.

 The install process will ask you if you accept the properties before starting.
For a  non-interactive version of the install, run
ant -Dproperties.accepted=yes install

To log the output in build.log, run
ant -Dproperties.accepted=yes -logfile build.log install

Under Linux, Java and C/C++ compilation is carried out. For windows, since Visual Studio is not a standard component, only Java compilation is carried out. Pre-compiled binaries are provided for the C/C++ components (packages and Greenstone 2 style building). If you have Visual Studio installed (version 6), you can run the compile-windows-c++ targets to compile the code locally. (Don't forget to setup the Visual Studio environment first, by running, e.g. C:/Program Files/Microsoft Visual Studio/VC98/Bin/VCVARS32.BAT or equivalent.)

Running Greenstone:
-------------------

To startup the servers, run 'ant start'. 'ant restart' and 'ant stop' restarts and shuts down the servers. To start or stop just Tomcat or MYSQL, use the start-tomcat, start-mysql, stop-tomcat, stop-mysql targets.

On Windows, if you have installed a binary version, you can also start Greenstone by selecting Greenstone 3 Digital Library from the Start menu.

Greenstone will be available in a browser at "http://localhost:8080/gsdl3".

Using SOAP (Linux and Windows):
-------------------------------

Greenstone comes with Apache Axis installed as a webapp in Tomcat.  A SOAP server on localsite is deployed during installation. You should be able to see all localsite's collections through the gateway servlet.

To set up a SOAP server on a new site, run
ant soap-deploy-site
This will prompt you for the sitename (the directory name), and the site uri - this should be a unique identifier for the site's web service.

For a non-interactive version, run
ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site

Building Collections:
-----------------------

You can build collections using either Greenstone 2 style building, or native Greenstone 3 style.

Greenstone 2:

You need to have Perl installed and on your PATH.
run  'ant gli", or cd to gsdl3/gli and run gli4gs3.sh/bat. This is a graphical tool for building collections.

Greenstone 3:

In the gsdl3 directory, run: 'source gs3-setup.sh' (linux) or 'gs3-setup' (windows).
To create a new collection, run 'gs3-mkcol.sh/bat <sitename> <collname>'
Put documents in the import directory (gsdl3/web/sites/<sitename>/collect/<collname>/import), edit the collection configuration file (gsdl3/web/sites/<sitename>/collect/<collname>/etc/collectionConfig.xml), and run 'gs3-build.sh <sitename> <collname>'
Rename the building directory to index (in gsdl3/web/sites/<sitename>/collect/<collname>) and reload the collection in Tomcat (?a=s&sa=a&st=collection&sn=<collname>), or restart Tomcat.

See the manual for more details about both styles of collection building.

Other Notes:
---------------

See gsdl3/docs/manual/manual.pdf for more details about the software and installation etc.

Under Linux, Tomcat logs output in gsdl3/comms/jakarta/tomcat/logs/catalina.out.

To prevent Tomcat showing directory listings, edit the gsdl3/comms/jakarta/tomcat/conf/web.xml file and set the value of the "listings" servlet parameter to false.

ant can't seem to do cvs using authenticated cvs on windows:
there were some classes missing - www.ibiblio.org/maven/jsch/jars/jsch-0.1.17.jar
many ssh processes seemed to be started up - all waiting in the background for password??
So should only use anonymous cvs.