source: trunk/gsdl3/README.txt@ 10741

Last change on this file since 10741 was 10741, checked in by kjdon, 18 years ago

few notes

  • Property svn:keywords set to Author Date Id Revision
File size: 15.2 KB
Line 
1Greenstone 3 (GSDL3)
2Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato
3GSDL3 comes with ABSOLUTELY NO WARRANTY; for details see LICENSE.txt
4This is free software, and you are welcome to redistribute it
5
6You will need Java and Ant to run Greenstone 3.
7
8Your 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.
9
10Ant (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
11
12In the gsdl3 directory, you can run 'ant' which will give you a help message.
13Running 'ant -projecthelp' gives a list of the targets that you can run - these
14do various things like compile the source code, start up the server etc.
15
16On Linux mysql seems to have trouble with spaces in paths, so it's best to install Greenstone into a path with no spaces.
17
18Installing Greenstone from a binary distribution:
19---------------------------------------------------------
20
21Download the appropriate zip/tar file (gsdl3-x.xx-linux.tar.gz/gsdl3-x.xx-win32.zip/gsdl3-x.xx-macOSX.tar.gz), and unzip/untar it. In the gsdl3 directory, edit the build.properties file if appropriate (see 'Configuring your installation' below), and run 'ant install'.
22
23Installing Greenstone from a CVS checkout (Linux/Windows/MacOS X):
24---------------------------------------------------------------------
25
26Make sure the CVS executable is on your PATH.
27
28Checkout the code:
29
30cvs -d :pserver:[email protected]:2402/usr/local/global-cvs/gsdl-src co gsdl3
31
32Build and install:
33
34In the gsdl3 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.
35
36The '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.
37
38Mac 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.
39
40Configuring your installation:
41------------------------------------
42
43The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
44
45Greenstone 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.
46
47Greenstone 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.
48
49Greenstone 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.
50
51The prepare/install target will ask you if you accept the properties before starting.
52To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
53ant -Dproperties.accepted=yes prepare install (from CVS), or
54ant -Dproperties.accepted=yes install (from binary dist).
55
56To log the output in build.log, run
57ant -Dproperties.accepted=yes -logfile build.log prepare install (from CVS), or
58ant -Dproperties.accepted=yes -logfile build.log install (from binary dist).
59
60The 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.)
61
62Common install/update targets (for use with Greenstone out of CVS).
63-------------------------------
641. Install for the first time from CVS:
65cvs co gsdl3
66cd gsdl3
67ant prepare install
68
692. Install for the first time from CVS, mostly offline:
70[online]
71cvs co gsdl3
72cd gsdl3
73ant prepare
74[offline]
75ant install
76
773. Install for the first time, with CVS done outside of Ant (if you have problems running CVS commands from Ant):
78cvs co -P gsdl3
79cd gsdl3/packages
80cvs co mgpp
81cd ..
82[if you want greenstone 2 building:
83cvs co -P gli
84cvs co -P gs2build
85]
86[if you are on windows
87cvs co winbin
88]
89ant -Dnocvs.mode=yes prepare install (prepare needs to be online, install can be done offline)
90
914. Updating your Greenstone installation from CVS (and reconfigure/recompile):
92cd gsdl3
93ant update
94
955. Updating your Greenstone installation from CVS, offline:
96cd gsdl3
97[online]
98ant cvsupdate
99[offline]
100ant -Dnocvs.mode=yes update
101
1026. Updating your Greenstone installation, with CVS done outside of Ant:
103cd gsdl3
104cvs update -l
105cvs update -dP bin comms docs lib resources src winutil packages
106cd web (or the path-to-tomcat/webapps/gsdl3 if have installed greenstone as a webapp in Tomcat, see Using External Tomcat section)
107cvs update -dP
108cd gsdl3
109[ if you have greenstone 2 building:
110cvs update -dP gli
111cvs checkout -P gs2build
112Note that the gs2build one uses checkout not update.
113]
114ant -Dnocvs.mode=yes update
115
116The main targets for installation/update are:
117configure, configure-c++, clean, compile.
118Any 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.
119
120If 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/gsdl3/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.
121
122Running Greenstone:
123-------------------
124
125To 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.
126These will only start/stop local servers (ones installed by Greenstone). You will need to manually start/stop external Tomcat/mysql.
127
128Greenstone will be available in a browser at "http://localhost:8080/gsdl3".
129
130You can change the port number by changing the 'tomcat.port' property in build.properties, then running 'ant configure'.
131
132
133Using SOAP (Linux and Windows):
134-------------------------------
135
136Greenstone 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.
137
138To set up a SOAP server on a new site, run
139ant soap-deploy-site
140This 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.
141
142For a non-interactive version, run
143ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
144
145The service is accessible at http://localhost:8080/gsdl3/services/<siteuri>
146(or http://<computer-web-address>:<port>/gsdl3/services/<siteuri>)
147
148Building Collections:
149-----------------------
150
151You can build collections using either Greenstone 2 style building, or native Greenstone 3 style.
152
153Greenstone 2:
154
155You need to have Perl installed and on your PATH. Perl is included as part of the Windows binary distribution.
156run 'ant gli", or cd to gsdl3/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.
157
158Note that GLI doesn't start up the Greenstone server (Tomcat/mysql) so you should run 'ant start' before previewing your collection.
159Greenstone 3:
160
161In the gsdl3 directory, run: 'source gs3-setup.sh' (Linux/Mac OS X) or 'gs3-setup' (windows).
162To create a new collection, run 'gs3-mkcol.sh/bat <sitename> <collname>'
163Put 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>'
164Rename 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.
165
166See the manual for more details about both styles of collection building.
167
168Other Notes:
169---------------
170
171See gsdl3/docs/manual/manual.pdf for more details about the software and installation etc.
172
173Under Linux, Tomcat logs output in gsdl3/comms/jakarta/tomcat/logs/catalina.out.
174
175To 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.
176
177ant can't seem to do cvs using authenticated cvs on windows:
178there were some classes missing - www.ibiblio.org/maven/jsch/jars/jsch-0.1.17.jar
179many ssh processes seemed to be started up - all waiting in the background for password??
180So should only use anonymous cvs.
181
182Using External Tomcat:
183------------------------
184
185If you want to use an existing Tomcat, set the path to its base directory
186in 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.
187
188 You will need to modify the Tomcat setup slightly.
189
1901. Tell Tomcat about the Greenstone web app. There are two ways to do this.
191
192A. Add in the Greenstone context to Tomcat's server.xml (In the Host name="localhost".. element)
193
194<Context path="/gsdl3" docBase="path-to-gsdl3/web" debug="1"
195reloadable="true"><Resources allowLinking='true'/></Context>
196
197B. Alternatively, you can move (and rename) the gsdl3/web directory to tomcat/webapps/gsdl3 (i.e. the resulting directories will be like
198tomcat/webapps/gsdl3/WEB-INF, no web directory). This should be done after running the initial 'ant [prepare] install'.
199You will need to set the web.home property in the build.properties file
200i.e.
201web.home=${tomcat.installed.path}/webapps/gsdl3
202And then run 'ant configure-web' to reset gsdl3home.
203
2042. Set up the JNI libraries and Java wrappers.
205JNI 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.
206The wrappers need to be loaded by this too.
207To 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).
208
209These JNI bits are located by default in the lib/jni directory. There are two ways to get them into Tomcat:
210A: Keep all the Greenstone stuff inside the gsdl3 directory, and just modify the environment that Tomcat runs in
211
212Set LD_LIBRARY_PATH (linux) or PATH (windows) to include the gsdl3/lib/jni directory.
213Add all the jar files in gsdl3/lib/jni directory to the CLASSPATH, then edit tomcats setclasspath.sh/bat to use the system CLASSPATH.
214(in setclasspath.bat, change
215set CLASSPATH=%JAVA_HOME%\lib\tools.jar
216to
217set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH%
218
219in setclasspath.sh, change
220# Set standard CLASSPATH
221if [ "$1" = "debug" -o "$1" = "javac" ] ; then
222 CLASSPATH="$JAVA_HOME"/lib/tools.jar
223fi
224
225to
226# Set standard CLASSPATH
227if [ "$1" = "debug" -o "$1" = "javac" ] ; then
228 CLASSPATH="$JAVA_HOME"/lib/tools.jar:"$CLASSPATH"
229fi
230
231
232B: Copy the files into Tomcat installation:
233Move the gsdl3/lib/jni jar files into tomcat's shared/lib directory.
234Move the gsdl3/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.
235This has the advantage that you can use this for other webapps without modifying the Tomcat environment.
236
237Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.
238
239Using External mysql server
240------------------------------
241
242Set the mysql.installed.path property in build.xml to be non-empty (its not actually used) before installation.
243
244You 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.
245
246Run mysql as the root user.
247
248Commands to add the two users:
249GRANT SELECT,INSERT,DELETE,UPDATE,DROP,CREATE ON *.* TO gsdl3admin@localhost identified by 'admin-password';
250GRANT SELECT ON *.* TO gsdl3reader@localhost identified by 'reader-password';
251
252You will need to edit the gsdl3/web/WEB-INF/classes/global.properties file and set the two passwords that you used in here:
253mysql.admin.password and mysql.reader.password
254The mysql.tcp.port property specified here should be set to the port that your mysql is running on. (default 3306).
255
256You should also load up the database for the gs3mgdemo collection:
257create database localsite_gs3mgdemo;
258
259Close mysql, then run
260mysql localsite_gs3mgdemo < <path-to-gsdl3>/web/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql
261
262(Note that if you have installed the Greenstone web directory into Tomcats webapps dir, then this command will be
263mysql localsite_gs3mgdemo < <path-to-tomcat>/webapps/gsdl3/sites/localsite/collect/gs3mgdemo/mysqldatadump.sql )
264
265You may need to run this using '--user=root -p'
266
267Notes for Mac OS
268------------------
269
270Set JAVA_HOME to be /Library/Java/Home
271
272Notes on Versions
273------------------
274
275Tomcat:
276jakarta-tomcat-5.5.7.zip & jakarta-tomcat-5.5.7-compat.zip
277Mysql:
278mysql-standard-4.1.11-pc-linux-gnu-i686.tar.gz
279mysql-standard-4.1.12-apple-darwin7.9.0-powerpc.tar.gz
280mysql-noinstall-4.1.11-win32.zip
281Axis:
282axis-bin-1_2_1.zip
283
284All available from www.greenstone.org/gs3files if not available at their respective websites.
Note: See TracBrowser for help on using the repository browser.