source: trunk/gsdl3/README.txt@ 13856

Last change on this file since 13856 was 13856, checked in by kjdon, 14 years ago

changed a comment about windows c++ compiling

  • Property svn:keywords set to Author Date Id Revision
File size: 13.0 KB
Line 
1Greenstone 3 (GSDL3)
2Copyright (C) 2003 New Zealand Digital Libraries, University Of Waikato
3Greenstone3 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 greenstone3 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
16Installing Greenstone
17---------------------------------------------------------
18
19Download the appropriate installer from sourceforge.net/projects/greenstone3 and run it.
20
21See 'Installing from a Source Distribution' section below for extra notes about installing from Source.
22
23See the README-CVS.txt file for extra notes about installing from CVS.
24
25Running Greenstone:
26---------------------------------------------------------
27
28To start up Greenstone, select Greenstone 2 Digital Library from the Start menu (Windows), or run gs3-server.sh/bat. This launches a small server program, which starts up Tomcat and launches a browser. A small window pops up which allows you to chnage some settings for your library and restart the Tomcat server. Closing this program will stop Tomcat running.
29
30Alternatively, you can start Tomcat directly through using Ant. 'ant start', 'ant restart' and 'ant stop' starts, restarts and shuts down Tomcat, respectively. This will only start/stop a local server (one installed by Greenstone). You will need to manually start/stop an external Tomcat (see below for notes about using a version of Tomcat external to Greenstone).
31
32Once the Tomcat server is running, Greenstone will be available in a browser at "http://localhost:8080/greenstone3" (or whatever port you specified during the
33installation process).
34You can change the port number using File->Settings in the server program, or by changing the 'tomcat.port' property in build.properties, then running 'ant configure'.
35
36Building Collections:
37----------------------------------------------------------
38
39You need to have Perl installed and on your PATH. Perl is included as part of
40the Windows binary distribution.
41run 'ant gli", or cd to greenstone3/gli and run gli4gs3.sh/bat. This is a
42graphical tool for building collections. Once you have created and built a
43collection, you can see it by clicking 'Preview collection' on the Build panel.
44
45Note that GLI doesn't start up the Greenstone Tomcat server so you should
46run 'ant start' before previewing your collection.
47
48
49Greenstone Admin
50------------------------------------------------------
51
52The Greenstone admin tool is currently under development.
53
54Using SOAP:
55-------------------------------------------------------
56
57Greenstone comes with Apache Axis installed as part of the Greenstone web application. However, no SOAP services are deployed by default.
58
59To deploy a SOAP server for localsite, run 'ant deploy-localsite'. You should now be able to see all localsite's collections through the gateway servlet. (http://localhost:8080/greenstone3/gateway)
60
61To set up a SOAP server on a new site, run
62ant soap-deploy-site
63This 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.
64
65For a non-interactive version, run
66ant -Daxis.sitename=xxx -Daxis.siteuri=yyy soap-deploy-site
67
68The service is accessible at http://localhost:8080/greenstone3/services/<siteuri>
69(or http://<computer-web-address>:<port>/greenstone3/services/<siteuri>)
70
71Note: Deploying a SOAP service for any site other than localsite requires the Greenstone source code to be installed. This is not installed by default for a binary distribution. To get the source code, re-run the installer, select custom install and deselect everything except the source code.
72
73Using External Tomcat:
74---------------------------------------------------
75
76If you want to use an existing Tomcat, set the path to its base directory
77in build.properties (tomcat.installed.path). Also set the tomcat.port property to be the port you are running Tomcat on, and change tomcat.server if the web address is not localhost. Then run 'ant configure'.
78
79 You will need to modify the Tomcat setup slightly.
80
811. Tell Tomcat about the Greenstone web app. There are two ways to do this.
82
83A. Copy the file greenstone3/resources/tomcat/greenstone3.xml into Tomcat's conf/Catalina/localhost directory. You'll need to edit the file and replace @gsdl3webhome@ with the full path to the web directory of your greenstone 3 installation. Any path separator is fine here ('/', '\\', '\').
84
85B. Alternatively, you can move (and rename) the greenstone3/web directory to tomcat/webapps/greenstone3 (i.e. the resulting directories will be like
86tomcat/webapps/greenstone3/WEB-INF, no web directory). This should be done after running the initial 'ant install'.
87
88You will need to set the web.home property in the build.properties file
89i.e.
90web.home=${tomcat.installed.path}/webapps/greenstone3
91And then run 'ant configure' to reset gsdl3home.
92
932. Set up the JNI libraries and Java wrappers.
94JNI 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.
95The wrappers need to be loaded by this too.
96
97These JNI bits are located by default in the lib/jni directory. There are two ways to get them into Tomcat:
98A: Keep all the Greenstone stuff inside the greenstone3 directory, and just modify the environment that Tomcat runs in
99
100Set LD_LIBRARY_PATH (GNU/Linux), DYLD_LIBRARY_PATH (Mac OS X) or PATH/Path (windows) to include the greenstone3/lib/jni directory.
101Add all the jar files in greenstone3/lib/jni directory to the CLASSPATH, then edit tomcats setclasspath.sh/bat to use the system CLASSPATH.
102(in setclasspath.bat, change
103set CLASSPATH=%JAVA_HOME%\lib\tools.jar
104to
105set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%CLASSPATH%
106
107in setclasspath.sh, change
108# Set standard CLASSPATH
109if [ "$1" = "debug" -o "$1" = "javac" ] ; then
110 CLASSPATH="$JAVA_HOME"/lib/tools.jar
111fi
112
113to
114# Set standard CLASSPATH
115if [ "$1" = "debug" -o "$1" = "javac" ] ; then
116 CLASSPATH="$JAVA_HOME"/lib/tools.jar:"$CLASSPATH"
117fi
118
119
120B: Copy the files into Tomcat installation:
121Move the greenstone3/lib/jni jar files into tomcat's shared/lib directory.
122Move the greenstone3/lib/jni library files (.so for GNU/Linux, .jnilib for Mac OS X .dll for Windows) into shared/classes, and set LD_LIBARARY_PATH (GNU/Linux), DYLD_LIBRARY_PATH (Mac OS X) or PATH/Path (Windows) to include this directory.
123 This has the advantage that you can use this for other webapps without modifying the Tomcat environment.
124
125Once all these changes have been made, you will need to restart the Tomcat server for them to take effect.
126
127
128Notes for Mac OS
129------------------------------------------------
130
131Set JAVA_HOME to be /Library/Java/Home
132
133Notes for Windows
134-----------------------------------------------
135
136You can set environment variables by going to Control Panel->System->Advanced->Environment Variables.
137
138Installing from a Source Distribution
139----------------------------------------------
140
141Download the greenstone-3.xx-src.tar.gz package from sourceforge.net/projects/greenstone3, and unpack it.
142In the greenstone3 directory, edit the build.properties file and run
143ant prepare install
144
145Tomcat will be installed as part of the prepare process. To stop this set the tomcat.installed.path to be the root of an existing Tomcat installation.
146
147* Solaris notes:
148** Make sure /usr/local/bin is in your PATH ahead of /usr/bin etc.
149** Add /usr/local/lib to LD_LIBARY_PATH
150** The gdbm database files (gs2mgdemo and gs2mgppdemo collections) were generated on a Mac, and don't seem to be compatible with Solaris. A text version of the file (database.txt) is included in the index/text directory. After installing Greenstone, and before running it, you'll need to:
151in greenstone3/gs2build directory: run 'source setup.bash' (Or if you have greenstone 2 already installed, run 'source setup.bash' in your greenstone 2 installation)
152in greenstone3/web/sites/localsite/collect/gs2mgdemo/index/text directories, run 'txt2db gs2mgdemo.bdb < database.txt'
153in greenstone3/web/sites/localsite/collect/gs2mgppdemo/index/text directories, run 'txt2db gs2mgppdemo.bdb < database.txt'
154** GLI shell scripts may not work like "./gli4gs3.sh". In this case, run "bash ./gli4gs3.sh" etc. You will need to compile GLI by hand (run "bash ./makegli.sh" in greenstone3/gli directory).
155** Set CC=gcc environment variable if you don't have cc, before running ant install.
156
157* Windows notes:
158** You need to have Visual Studio installed to compile the C/C++ code. Set the path to the setup file in build.properties (compile.windows.c++.setup).
159
160Configuring your installation:
161--------------------------------------------------------
162
163The file build.properties contains various parameters that can be set by the user. Please check these settings before running the install.
164Note, either forward slash '/' or double backslash '\\' can be used as path separators in the build.properties file, but not single backslash '\'.
165
166Greenstone 3 comes with Tomcat bundled in.
167
168If 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 use its own Tomcat. (You can delete the packages/tomcat directory if you like.) Please read the section "Using External Tomcat" for details about how to configure Tomcat for Greenstone.
169
170Mac OS X: 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.
171
172The install target will ask you if you accept the properties before starting.
173To suppress this prompt, use the -Dproperties.accepted=yes flag. E.g.
174ant -Dproperties.accepted=yes install
175
176To log the output in build.log, run
177ant -Dproperties.accepted=yes -logfile build.log install
178
179Recompiling
180-------------------------------------------------------
181To recompile your Greenstone3 installation, in the top level greenstone3 directory, run:
182
183ant configure
184ant configure-c++
185ant clean
186ant compile
187
188The compile target does Java and C/C++ compilation. On Windows, you need to set the compile.windows.c++.setup property to be your Visual Studio setup batch file.
189
190Any 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.
191
192
193Notes on Versions of Third Party packages
194-----------------------------------------------
195
196Tomcat:
197
198apache-tomcat-5.5.12.zip: latest production quality release as of October, 2005.
199apache-tomcat-5.5.12-compat.zip: Tomcat 5 requires Java 1.5. If using Java 1.4, need to use this compatibility module.
200
201website: http://tomcat.apache.org/
202download: http://tomcat.apache.org/download-55.cgi
203
204Axis:
205
206Apache Web Services Project, SOAP implementation. Axis is a follow on project to Apache SOAP
207
208axis-bin-1_2_1.zip: latest stable release as of October, 2005
209website: http://ws.apache.org/axis/
210download: http://www.apache.org/dyn/closer.cgi/ws/axis/1_2_1
211
212All available from www.greenstone.org/gs3files if not available at their respective websites.
213
214Other Notes:
215-------------------------------------------------
216
217See greenstone3/docs/manual/manual.pdf for more details about the software and installation etc.
218
219Output is logged to web/logs. usage.log is a usage log, while greenstone.log is the error/message log. To change the level of logging, edit the web/WEB-INF/classes/log4j.properties file, and change the log4j.disable property. Valid values are TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
220
221To prevent Tomcat showing directory listings, edit Tomcat's conf/web.xml file and set the value of the "listings" servlet parameter to false.
222
223To enable symlinks to files outside the webapp root directory, edit Tomcat's conf/Catalina/localhost/greenstone3.xml file, and set the allowLinking attribute in the Context element to true.
224(Note from Tomcat website: This flag MUST NOT be set to true on the Windows platform (or any other OS which does not have a case sensitive filesystem), as it will disable case sensitivity checks, allowing JSP source code disclosure, among other security problems.)
225
226The file web/WEB-INF/classes/global.properties is generated on install and contains some properties for the run time system.
227
Note: See TracBrowser for help on using the repository browser.