source: trunk/gsdl3/README.txt@ 10800

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

You will need Java and Ant to run Greenstone 3. 

Your Java version should be 1.4 or higher. We recommend Sun Java. You need the SDK (development environment). Set the environment variable JAVA_HOME to be the root of your Java installation.

Ant (Apache's Java based build tool) can be downloaded from http://ant.apache.org/bindownload.cgi. Set the environment variable ANT_HOME to be the root of your Ant installation, and make sure the Ant executables are on your PATH. You may have problems with earlier versions. This has been tested with version 1.6.2

In the greenstone3 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, start up the server etc.

On Linux mysql seems to have trouble with spaces in paths, so it's best to install Greenstone into a path with no spaces.

Installing Greenstone from a binary distribution:
---------------------------------------------------------

Download the appropriate zip/tar file (greenstone-3.xx-linux.tar.gz/greenstone-3.xx-win32.zip/greenstone-3.xx-macOSX.tar.gz), and unzip/untar it. In the greenstone3 directory, edit the build.properties file if appropriate (see 'Configuring your installation' below), and run 'ant install'.

Installing Greenstone from a CVS checkout (Linux/Windows/MacOS X):
---------------------------------------------------------------------

Make sure the CVS executable is on your PATH.

Checkout the code:

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

Build and install:

In the greenstone3 directory, edit the build.properties file if appropriate (see 'Configuring your installation' below), and run 'ant prepare install'. The two targets can be run separately if you like.

The 'prepare' target will download additional code (using CVS and http), so you need to be online to run it. The 'install' target can be run offline.

Mac OS X: If you want to do Greenstone 2 style collection building, you need to have GDBM installed (http://www.gnu.org/software/gdbm/gdbm.html). Please set the gdbm.installed.path property (in build.properties) to the root of your gdbm installation if it is not installed in a default place. If you run GLI or GS2 collection building from the command line, you will need to set the DYLD_LIBRARY_PATH environment variable to include <path-to-gdbm>/lib.

Configuring your installation:
------------------------------------

The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.

Greenstone 3 uses the Tomcat servlet container. If you already have Tomcat running, you can set the 'tomcat.installed.path' property (in build.properties) to the base directory of your Tomcat installation, and Greenstone will not download/install its own Tomcat. Please read the section "Using External Tomcat" for details about how to configure Tomcat for Greenstone.

Greenstone 3 uses mysql for the collection database (with Greenstone 3 native building). If you already have mysql installed, set the 'mysql.installed.path' property (in build.properties) to the base directory of your mysql installation, and Greenstone will not download/install mysql. Please read the section "Using external mysql server" for details about how to configure mysql for Greenstone.
If you are using mysql that comes with greenstone 3, and you are installing greenstone 3 on an NFS drive, mysql may not work properly (it has problems removing locks on its data files). After installation, copy the data directory from greenstone3/packages/mysql to a local drive, then set the path to this directory in the mysql.datadir property in build.properties.

Greenstone 3 uses some parts of Greenstone 2 for collection building using the Librarian Interface. These will be installed during the Greenstone 3 installation process. If you have Greenstone 2 already installed and want to use that version instead, please set the gsdl2.installed.path property (in build.properties) to be the root of your Greenstone 2 installation. Greenstone 3 will then use this installation rather than its own bits. (Note, be careful about compatibility between versions.) If you are using Greenstone 3 from CVS, and don't want to download the Greenstone 2 stuff, set the gsdl2.installed.path to any non-empty string.

The prepare/install target will ask you if you accept the properties before starting.
To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
ant -Dproperties.accepted=yes prepare install (from CVS), or
ant -Dproperties.accepted=yes install (from binary dist).

To log the output in build.log, run
ant -Dproperties.accepted=yes -logfile build.log prepare install (from CVS), or
ant -Dproperties.accepted=yes -logfile build.log  install (from binary dist).

The compile target, under Linux, does Java and C/C++ compilation. 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.)

Common install/update targets (for use with Greenstone out of CVS).
-------------------------------
1. Install for the first time from CVS:
cvs co greenstone3
cd greenstone3
ant prepare install

2. Install for the first time from CVS, mostly offline:
[online]
cvs co greenstone3
cd greenstone3
ant prepare
[offline]
ant install

3. Install for the first time, with CVS done outside of Ant (if you have problems running CVS commands from Ant):
cvs co -P greenstone3
cd greenstone3/packages
cvs co mgpp
cd ..
[if you want greenstone 2 building:
cvs co -P gli
cvs co -P gs2build
]
[if you are on windows
cvs co winbin
]
ant -Dnocvs.mode=yes prepare install (prepare needs to be online, install can be done offline)

4. Updating your Greenstone installation from CVS (and reconfigure/recompile):
cd greenstone3
ant update

5. Updating your Greenstone installation from CVS, offline:
cd greenstone3
[online]
ant cvsupdate
[offline]
ant -Dnocvs.mode=yes update

6. Updating your Greenstone installation, with CVS done outside of Ant:
cd greenstone3
cvs update -l
cvs update -dP bin comms docs lib resources src winutil packages 
cd web (or the path-to-tomcat/webapps/greenstone3 if have installed greenstone as a webapp in Tomcat, see Using External Tomcat section)
cvs update -dP 
cd greenstone3
[ if you have greenstone 2 building:
cvs update -dP gli
cvs checkout -P gs2build
Note that the gs2build one uses checkout not update.
]
ant -Dnocvs.mode=yes update

The main targets for installation/update are:
configure, configure-c++, clean, compile.
Any sub targets can be run by themselves. Run 'ant -projecthelp' for a list of public targets, otherwise you can look at the build.xml file to see which targets depend on other ones.

If you run your install using an external Tomcat, the SOAP web service for localsite (used by the gateway servlet) will not be loaded. You need to start up Tomcat, then run 'ant soap-deploy-site' and accept the defaults for sitename and siteuri (both localsite). If you want to use the gateway servlet without restarting Tomcat, you will need to reload the site information. Visit the URL localhost:8080/greenstone3/gateway?a=s&sa=c  (substituting your server name and port number if necessary). See the user guide for more information about run time reconfiguration.

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

To startup the local 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.
These will only start/stop local servers (ones installed by Greenstone). You will need to manually start/stop external Tomcat/mysql.

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

You can change the port number by changing the 'tomcat.port' property in build.properties, then running 'ant configure'.


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

Greenstone comes with Apache Axis installed as part of the Greenstone web application.  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

The service is accessible at http://localhost:8080/greenstone3/services/<siteuri>
(or http://<computer-web-address>:<port>/greenstone3/services/<siteuri>)

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. Perl is included as part of the Windows binary distribution.
run  'ant gli", or cd to greenstone3/gli and run gli4gs3.sh/bat. This is a graphical tool for building collections. Once you have created and built a collection, you can see it by clicking 'Preview collection' on the Build panel.

Note that GLI doesn't start up the Greenstone server (Tomcat/mysql) so you should run 'ant start' before previewing your collection.
Greenstone 3:

In the greenstone3 directory, run: 'source gs3-setup.sh' (Linux/Mac OS X) or 'gs3-setup' (windows).
To create a new collection, run 'gs3-mkcol.sh/bat <sitename> <collname>'
Put documents in the import directory (greenstone3/web/sites/<sitename>/collect/<collname>/import), edit the collection configuration file (greenstone3/web/sites/<sitename>/collect/<collname>/etc/collectionConfig.xml), and run 'gs3-build.sh <sitename> <collname>'
Rename the building directory to index (in greenstone3/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 greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.

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

To prevent Tomcat showing directory listings, edit the greenstone3/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.

Using External Tomcat:
------------------------

If you want to use an existing Tomcat, set the path to its base directory
in build.properties (tomcat.installed.path) (on windows need to use double backslashes in paths '\\'). Then run 'ant prepare install'. If you have already done an install (e.g. using a local Tomcat), you don't need to do it again.

 You will need to modify the Tomcat setup slightly.

1. Tell Tomcat about the Greenstone web app. There are two ways to do this.

A. Add in the Greenstone context to Tomcat's server.xml (In the Host name="localhost".. element)

<Context path="/greenstone3" docBase="path-to-greenstone3/web" debug="1" 
reloadable="true"><Resources allowLinking='true'/></Context>

B. Alternatively, you can move (and rename) the greenstone3/web directory to tomcat/webapps/greenstone3 (i.e. the resulting directories will be like
tomcat/webapps/greenstone3/WEB-INF, no web directory). This should be done after running the initial 'ant [prepare] install'.
You will need to set the web.home property in the build.properties file
i.e.
web.home=${tomcat.installed.path}/webapps/greenstone3
And then run 'ant configure-web' to reset gsdl3home.

2. Set up the JNI libraries and Java wrappers.
JNI libraries and their Java wrappers cannot go into the web app. The libraries need to be loaded by the same class loader as their wrappers. The libraries need to be in java.library.path, and I think get loaded by the system class loader.
The wrappers need to be loaded by this too. 
To get the native libraries loaded, the directory they are in needs to be in the PATH variable (Windows) or the LD_LIBRARY_PATH variable (linux).

These JNI bits are located by default in the lib/jni directory. There are two ways to get them into Tomcat:
A: Keep all the Greenstone stuff inside the greenstone3 directory, and just modify the environment that Tomcat runs in

Set LD_LIBRARY_PATH (linux) or PATH (windows) to include the  greenstone3/lib/jni directory.
Add all the jar files in greenstone3/lib/jni directory to the CLASSPATH, then edit tomcats setclasspath.sh/bat to use the system CLASSPATH.
(in setclasspath.bat, change 
set CLASSPATH=%JAVA_HOME%\lib\tools.jar
to 
set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH%

in setclasspath.sh, change
# Set standard CLASSPATH
if [ "$1" = "debug" -o "$1" = "javac" ] ; then
  CLASSPATH="$JAVA_HOME"/lib/tools.jar
fi

to
# Set standard CLASSPATH
if [ "$1" = "debug" -o "$1" = "javac" ] ; then
  CLASSPATH="$JAVA_HOME"/lib/tools.jar:"$CLASSPATH"
fi


B: Copy the files into Tomcat installation:
Move the greenstone3/lib/jni jar files into tomcat's shared/lib directory.
Move the greenstone3/lib/jni library files (.so for linux, .dll for windows) into shared/classes, and set LD_LIBARARY_PATH (linux) or PATH (windows) to include this directory. 
This has the advantage that you can use this for other webapps without modifying the Tomcat environment.

Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.

Using External mysql server
------------------------------

Set the mysql.installed.path property in build.xml to be non-empty (its not actually used) before installation.

You will need to add the two greenstone users: gsdl3reader and gsdl3admin. The reader user is only used for accessing the database, the admin user can be used for modification.

Run mysql as the root user.

Commands to add the two users:
GRANT SELECT,INSERT,DELETE,UPDATE,DROP,CREATE ON *.* TO gsdl3admin@localhost identified by 'admin-password';
GRANT SELECT ON *.* TO gsdl3reader@localhost identified by 'reader-password';

You will need to edit the greenstone3/web/WEB-INF/classes/global.properties file and set the two passwords that you used in here:
mysql.admin.password and mysql.reader.password
The mysql.tcp.port property specified here should be set to the port that your mysql is running on. (default 3306).

You should also load up the database for the gs3mgdemo collection:
create database localsite_gs3mgdemo;

Close mysql, then run
mysql localsite_gs3mgdemo < <path-to-greenstone3>/web/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql

(Note that if you have installed the Greenstone web directory into Tomcats webapps dir, then this command will be
mysql localsite_gs3mgdemo < <path-to-tomcat>/webapps/greenstone3/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql )

You may need to run this using '--user=root -p'

Notes for Mac OS
------------------

Set JAVA_HOME to be /Library/Java/Home

Notes on Versions
------------------

Tomcat: 
jakarta-tomcat-5.5.7.zip & jakarta-tomcat-5.5.7-compat.zip
Mysql: 
mysql-standard-4.1.11-pc-linux-gnu-i686.tar.gz
mysql-standard-4.1.12-apple-darwin7.9.0-powerpc.tar.gz
mysql-noinstall-4.1.11-win32.zip
Axis:
axis-bin-1_2_1.zip

All available from www.greenstone.org/gs3files if not available at their respective websites.