source: trunk/gsdl3/README.txt@ 10674

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

some changes to reflect the binary distribution installation procedure

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