source: branches/ant-install-branch/gsdl3/README.txt@ 10798

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