Changeset 9843
- Timestamp:
- 2005-05-09T12:01:56+12:00 (19 years ago)
- Location:
- branches/ant-install-branch/gsdl3/docs/manual
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
branches/ant-install-branch/gsdl3/docs/manual/manual.tex
r9445 r9843 66 66 This section covers where to get \gsiii\ from, how to install it and how to run it. The standard method of running \gsiii\ is as a Java servlet. We provide the Tomcat servlet container to run the servlet. Standard web servers may be able to be configured to provide servlet support, and thereby remove the need to use Tomcat. Please see your web server documentation for this. This documentation assumes that you are using Tomcat. To access \gsiii, Tomcat must be started up, and then it can be accessed via a web browser. 67 67 68 Ant (Java's XML based build tool) is used for compilation, installation and running Greenstone. The build.xml file is the configuration file for the Greenstone project, and build.properties contains parameters that can be altered by the user. 68 69 69 70 \subsection{Get and install \gs\ } … … 75 76 \subsubsection{Linux} 76 77 77 Download the latest version of the installer, \gst{gsdl3-x.xx-linux}, and run it in a shell (\gst{./gsdl3-x.xx-linux}). The installation process will prompt you for the installation directory, the name of your computer and what port to run Tomcat on ( the defaults being \gst{localhost} and \gst{8080}). Once \gsiii\ has been installed, you can start the library by running \gst{.gs3-launch.sh} from the gsdl3 directory, and opening up a browser pointing to \gst{http://localhost:8080/gsdl3} (substituting your chosen name and port if necessary).78 Download the latest version of the installer, \gst{gsdl3-x.xx-linux}, and run it in a shell (\gst{./gsdl3-x.xx-linux}). The installation process will prompt you for the installation directory, the name of your computer and what port to run Tomcat on (defaults are \gst{localhost} and \gst{8080}). Once \gsiii\ has been installed, you can start the library by running \gst{ant start} from the gsdl3 directory, and opening up a browser pointing to \gst{http://localhost:8080/gsdl3} (substituting your chosen name and port if necessary). 78 79 79 80 \subsubsection{Windows} 80 81 81 Download the latest Windows installer, \gst{gsdl3-x.xx-win32.exe}, and double click it to start the installation. You will be prompted for the installation directory, installation type, your computer name and the port number to run Tomcat on (defaults are \gst{localhost} and \gst{8080}). Once \gsiii\ is installed, you can access the library by selecting \gst{Greenstone Digital Library 3} in the Start menu .82 Download the latest Windows installer, \gst{gsdl3-x.xx-win32.exe}, and double click it to start the installation. You will be prompted for the installation directory, installation type, your computer name and the port number to run Tomcat on (defaults are \gst{localhost} and \gst{8080}). Once \gsiii\ is installed, you can access the library by selecting \gst{Greenstone Digital Library 3} in the Start menu (or by running \gst{ant start} in the gsdl3 directory). 82 83 83 84 \subsubsection{Accessing the library in a browser}\label{sec:browser-access} … … 93 94 \subsubsection{Restarting the library} 94 95 95 The library program (actually Tomcat) can be restarted in Windows by closing the window, and restarting it from the Start menu. In Linux, you need to go to the gsdl3 directory, and run \gst{ ./gs3-launch.sh -shutdown}, then \gst{./gs3-launch.sh}.96 The library program (actually Tomcat) can be restarted in Windows by closing the window, and restarting it from the Start menu. In Linux, you need to go to the gsdl3 directory, and run \gst{ant restart}. 96 97 97 98 … … 366 367 \begin{figure}[h] 367 368 \centering 368 \includegraphics[width=4in]{pagebanner } %5.8369 \includegraphics[width=4in]{pagebanner.ps} %5.8 369 370 \caption{A sample collection page banner} 370 371 \label{fig:page-banner} … … 389 390 390 391 To create the director 391 Building native \gsiii\ collections is done using the \gst{gs3-build.sh } script, with the \gst{collectionConfig.xml} file controlling how the building is done. There are a number of considerations in building a collection: what documents appear in the collection, how they are indexed for searching, which classifications are used for browsing, etc.392 Building native \gsiii\ collections is done using the \gst{gs3-build.sh/bat} script, with the \gst{collectionConfig.xml} file controlling how the building is done. There are a number of considerations in building a collection: what documents appear in the collection, how they are indexed for searching, which classifications are used for browsing, etc. 392 393 393 394 Firstly, the documents that comprise the collection should be placed in the import subdirectory. At present, only documents in this directory will appear in the collection. Documents can be organised into sub folders inside the import directory. … … 453 454 The collectionConfig.xml file controls the all of these options for collection building, and the format is described in Section~\ref{sec:collconfig}. 454 455 455 To build a collection, place the source documents and optional metadata.xml file(s) in the import directory, place the \gst{collectionConfig.xml} file in the etc directory, and execute \gst{gs3build.sh/bat sitename collectionname}. The process will run, placing the new indexes in the \gst{building} subdirectory of the collection's directory. You must have mysql running before you start building---running \gst{ gs3-launch.sh/bat} will start up the MySQL server as well as tomcat.456 To build a collection, place the source documents and optional metadata.xml file(s) in the import directory, place the \gst{collectionConfig.xml} file in the etc directory, and execute \gst{gs3build.sh/bat sitename collectionname}. The process will run, placing the new indexes in the \gst{building} subdirectory of the collection's directory. You must have mysql running before you start building---running \gst{ant start} will start up the MySQL server as well as tomcat. 456 457 457 458 Once the build process is complete, the building directory should be renamed to index (after deleting or renaming the existing index directory, if any), and Tomcat prompted to reload the collection---either by restarting the server, or by sending an activate collection command to the library servlet. … … 1031 1032 \begin{figure}[t] 1032 1033 \centering 1033 \includegraphics[width=4in]{ newlocal} %5.81034 \includegraphics[width=4in]{local} %5.8 1034 1035 \caption{A simple stand-alone site.} 1035 1036 \label{fig:local} … … 2176 2177 \end{figure} 2177 2178 2178 We have used Apache SOAP for Java. This is run as a servlet in Tomcat. Tomcat in Greenstone comes set up to use SOAP, but it is not enabled. To enable it, run \gst{gs3-enable-soap.sh/bat}. For more details about SOAP in Greenstone, see Appendix~\ref{app:soap}. Debugging soap is described in Appendix~\ref{app:soap-debug}.2179 We have used Apache Axis SOAP implementation. This is run as a servlet in Tomcat. Axis is setup during installation of Greenstone. For more details about SOAP in Greenstone, see Appendix~\ref{app:soap}. Debugging soap is described in Appendix~\ref{app:soap-debug}. 2179 2180 2180 2181 \subsection{Serving a site using soap} 2181 2182 2182 A script has been created to setup a SOAP server for a site. On Linux, from the gsdl3 directory, run 2183 \gst{./gs3-soap-deploy-site.sh <sitename> <siteuri>} 2184 2185 Sitename is the name of the site's directory, e.g. localsite. The siteuri is the identifier that will be used for the SOAP resource, e.g. org.greenstone.localsite. It should be a unique name amongst all the SOAP services that you want to connect to. 2186 2187 The script deploys the service for the site specified. A resource file (\gst{sitename.xml}) is created which is used to specify the service. It can be found in \gst{gsdl3/resources/soap}, and is generated from \gst{site.xml.in}. 2183 A webs service for localsite comes predeployed, but if you want to setup a service for another site, run \gst{ant soap-deploy-site}. This will prompt you for the sitename (its directory name), and a siteuri - a unique identifier for the web service. 2184 2185 The ant target deploys the service for the site specified. A resource file (\gst{<sitename>.wsdd}) is created which is used to specify the service. It can be found in \gst{gsdl3/resources/soap}, and is generated from \gst{site.wsdd.template}. 2188 2186 2189 2187 To get siteA to talk to siteB, you need to deploy a SOAP server on siteB, then add a \gst{<site>} element to the \gst{<siteList>} of siteA's \gst{siteConfig.xml} file (in \gst{gsdl3/web/sites/siteA/siteConfig.xml}). … … 2193 2191 \begin{gsc}\begin{verbatim} 2194 2192 <site name="siteAuri" 2195 address="http://localhost:8080/ soap/servlet/rpcrouter"2193 address="http://localhost:8080/axis/services/siteAuri" 2196 2194 type="soap"/> 2197 2195 \end{verbatim}\end{gsc} … … 2208 2206 \gsiii\ is also available via CVS. You can download the latest version of the code. This is not guaranteed to be stable, in fact it is likely to be unstable. The advantage of using CVS is that you can update the code and get the latest fixes. 2209 2207 2210 Note that you will need the Java 2 SDK, version 1.4.0 or higher .2208 Note that you will need the Java 2 SDK, version 1.4.0 or higher, and Ant (Apache's Java based build tool, http://ant.apache.org) installed. 2211 2209 2212 2210 To check out the \gs\ code, use: … … 2219 2217 If you need it, the password for anonymous CVS access is \gst{anonymous}. Note that some older versions of CVS have trouble accessing this repository due to the port number being present. We are using version 1.11.1p1. 2220 2218 2221 The software needs to be compiled and installed. The installation procedure uses a shell script or batch file. The most up to date instructions may be found in the README.txt file in the top level gsdl3 directory. 2222 2223 To install Greenstone once you have checked it out of CVS, do the following (alternatives for Linux or Windows): 2219 Greenstone is built and installed using Ant (Apache's Java based build tool, 2220 http://ant.apache.org). You will need a Java Development 2221 Environment (1.4 or higher), and Ant installed to use Greenstone. You can download Ant from http://ant.apache.org/bindownload.cgi. 2222 2223 In the gsdl3 directory, you can run 'ant' which will give you a help message. 2224 Running 'ant -projecthelp' gives a list of the targets that you can run - these 2225 do various things like compile the source code, startup the server etc. 2226 2227 For a first time install, run 'ant install'. 2228 2229 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. 2230 For a non-interactive version of the install, run 2231 ant -Dproperties.accepted=yes install 2232 2233 To log the output in build.log, run 2234 ant -Dproperties.accepted=yes -logfile build.log install 2235 2236 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.) 2237 2238 2239 Note: \gst{gs3-setup} sets the environment variables \gst{CLASSPATH, PATH, JAVA\_HOME} and needs to be done in a shell before doing collection building etc. 2240 2241 To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are (run from the gsdl3 directory): 2224 2242 2225 2243 \begin{quote}\begin{gsc} 2226 cd gsdl3\\ 2227 ./gs3-install.sh or gs3-install\\ 2228 source gs3-setup.sh or gs3-setup 2244 ant start \\ 2245 ant stop 2229 2246 \end{gsc}\end{quote} 2230 2247 2231 To recompile the code at any stage, you can use 2232 \begin{quote}\begin{gsc} 2233 source gs3-setup.sh or gs3-setup\\ 2234 make\\ 2235 make install\\ 2236 \end{gsc}\end{quote} 2237 2238 Note: \gst{gs3-setup} sets the environment variables \gst{CLASSPATH, PATH, JAVA\_HOME} and needs to be done in a shell before doing collection building etc. 2239 2240 To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are (run from the gsdl3 directory): 2241 \begin{quote}\begin{gsc} 2242 ./gs3-launch.sh or gs3-launch \\ 2243 ./gs3-launch.sh -shutdown or close the window 2244 \end{gsc}\end{quote} 2245 2248 If you want to restart only Tomcat, run \gst{ant restart-tomcat}. 2246 2249 2247 2250 \newpage 2248 2251 \section{Tomcat}\label{app:tomcat} 2249 2252 2250 Tomcat is a servlet container . It is used to serve a \gs\ site using a servlet.2253 Tomcat is a servlet container, and Greenstone 3 runs as a servlet inside it. 2251 2254 2252 2255 The file \gst{\gsdlhome/comms/jakarta/tomcat/conf/server.xml} is the Tomcat configuration file. The installation process adds a context for \gsiii\ servlets (\gst{\gsdlhome/web})---this tells Tomcat where to find the web.xml file, and what URL (\gst{/gsdl3}) to give it. Anything inside the context directory is accessible via Tomcat\footnote{can we use .htaccess files to restrict access??}. For example, the index.html file that lives in \gst{\gsdlhome/web} can be accessed through the URL \gst{localhost:8080/gsdl3/index.html}. The demo collection's images can be accessed through \\ … … 2254 2257 2255 2258 2256 Tomcat runs by default on port 8080---this can be changed in server.xml, in the \begin{quote}\begin{gsc} 2257 <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 -->\\ 2258 <Connector> 2259 \end{gsc}\end{quote} 2260 element. The siteConfig files also need changing if Tomcat's port is changed: \gst{<httpAddress>} for the site, and \gst{<address>} for a remote site both use this. 2259 Grenstone sets up Tomcat to run on port 8080 by default. To change this, you can edit the tomcat.port property in build.properties. If you do this before installing Greenstone, then running 'ant install' will use the new port number. If you want to change it later on, shutdown tomcat, run 'ant reconfigure-server-settings', then when you restart tomcat it will use the new port. 2261 2260 2262 2261 Note: Tomcat must be shutdown and restarted any time you make changes in the following for those changes to take effect: … … 2264 2263 \begin{gsc} 2265 2264 \item \gsdlhome/web/WEB-INF/web.xml 2266 \item \gsdlhome/comms/jakarta/tomcat -tomcat-4.0.1/conf/server.xml2265 \item \gsdlhome/comms/jakarta/tomcat/conf/server.xml 2267 2266 \end{gsc} 2268 2267 \item any classes or jar files used by the servlets 2269 2268 \end{bulletedlist} 2270 \noindent Note: stdin and stdout for the servlets both go to\\2269 \noindent Note: stdin and stdout for the servlets (on linux) both go to\\ 2271 2270 \gst{\gsdlhome/comms/jakarta/tomcat/logs/catalina.out} 2272 2271 … … 2282 2281 \end{gsc}\end{quote} 2283 2282 2284 We have set up Tomcat to disallow directory listings for everything in the docBase directory. To turn this back on, you need to edit Tomcat's default web.xml file (\gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/web.xml}): 2285 2286 In the default servlet definition, change the 'listings' parameter to true. 2283 By default, Tomcat allows directory listings. To disable this, change the 'listings' paramter to false in the default servlet definition, in Tomcat's web.xml file (\gst{\$GSDL3HOME/comms/jakarta/tomcat/conf/web.xml}): 2287 2284 2288 2285 Tomcat uses a Manager to handle HTTP session information. This may be stored between restarts if possible. To use a persistent session handling manager, uncomment the \gst{<Manager>} element in \\ … … 2314 2311 \section{SOAP}\label{app:soap} 2315 2312 2316 Grenstone uses Apache SOAP for distributed communications. This runs as a servlet inside Tomcat, and services can be deployed by the servlet. The SOAP servlet comes ready to run, but not enabled. To enable it, run: 2317 2318 \begin{quote}\begin{gsc} 2319 gs3-enable-soap.[sh/bat] 2320 \end{gsc}\end{quote} 2321 2322 All this does is to rename the SOAP web.xml.disabled file to web.xml. 2323 2324 The SOAP service for localsite comes pre-deployed. To get the gateway servlet talking to the localsite SOAP server, you need to shutdown and restart Tomcat. You should now see more collections when you run the gateway servlet. 2325 2326 To deploy a SOAP service for other sites, run 2327 \begin{quote}\begin{gsc} 2328 gs3-soap-deploy-site.[sh/bat] <sitename> <siteURI> 2329 \end{gsc}\end{quote} 2330 2331 This creates a new SOAPServer class for the site \\(\gst{\$GSDL3HOME/src/java/org/greenstone/gsdl3/SOAPServer<sitename>.java}), creates a resource file for deployment (\gst{\$GSDL3HOME/resources/soap/<sitename>.xml}), and then tries to deploy the service. If the deployment doesn't work, you can run it from the command line like: 2332 2333 \begin{gsc}\begin{verbatim} 2334 java org.apache.soap.server.ServiceManagerClient 2335 http://localhost:8080/soap/servlet/rpcrouter deploy 2336 resources/soap/<sitename>.xml 2337 \end{verbatim}\end{gsc} 2338 2339 You can also deploy a service through the website. If Tomcat is not running, start it up. 2340 2341 The SOAP servlet can be accessed at \begin{gsc}{\tt http://localhost:8080/soap}\end{gsc}. You should see a welcome page. Click on ``Run the admin client''. This enables you to list, deploy and undeploy SOAP services. 2342 2343 To deploy the SOAPServer for siteX: 2344 2345 Click on ``deploy'' and edit the following fields in the deploy form: 2346 2347 \begin{tabular}{ll} 2348 ID: & <URI for siteX>\\ 2349 Scope: (choose Session & Request---new instantiation for each request\\ 2350 or Application) & Session---same instantiation across a session\\ 2351 & Application---only uses one instantiation\\ 2352 Methods: &process\\ 2353 Java Provider / Provider Class: & org.greenstone.gsdl3.SOAPServersiteX\\ 2354 \end{tabular} 2355 2356 Now click the ``deploy'' button at the bottom of the page. If the service has been deployed, it should appear when you click on the left hand ``List'' button. 2357 2358 Information about deployed services is maintained between Tomcat sessions---you only need to deploy it once. 2313 Grenstone uses the Apache Axis SOAP implementation for distributed communications. Axis runs as a servlet inside Tomcat, and SOAP web services can be deployed by this Axis servlet. The Greenstone installation process sets up Axis for Tomcat, and predeploys the localsite web service. 2314 2315 To deploy a SOAP service for other sites, run \gst{ant soap-deploy-site} 2316 2317 This will prompt you for the sitename (the site's directory name), and a unique URI for the site. It creates a new SOAPServer class for the site \\(\gst{\$GSDL3HOME/src/java/org/greenstone/gsdl3/SOAPServer<sitename>.java}), creates a resource file for deployment (\gst{\$GSDL3HOME/resources/soap/<sitename>.wsdd}), and then tries to deploy the service. 2318 2319 Information about deployed services is maintained between Tomcat sessions---you only need to deploy something once. To undeploy a site, use \gst{ant undeploy-soap-site}. 2320 2321 The axis servlet can be accessed at \gst{localhost:8080/axis}. 2359 2322 2360 2323 \subsection{Debugging SOAP}\label{app:soap-debug} 2361 2324 2362 If you need to debug the SOAP stuff for some reason, or just want to look at the SOAP messages that are being passed back and forth, use a program called TcpTunnelGui. This intercepts messages coming in to one port, displays them, and passes them to another port.2325 If you need to debug the SOAP stuff for some reason, or just want to look at the SOAP messages that are being passed back and forth, you can use the TCP monitor. This intercepts messages coming in to one port, displays them, and passes them to another port. 2363 2326 To run it, type: 2364 2327 2365 \begin{quote}\gst{java org.apache.soap.util.net.TcpTunnelGui 8070 localhost 8080} 2328 \begin{quote}\gst{java -cp <path to gsdl3>/comms/soap/axis/lib/axis.jar \\ 2329 org.apache.axis.utils.tcpmon} 2366 2330 \end{quote} 2367 2331 2368 8070 is the port that TcpTunnelGui listens on, and 8080 is the port that it sends the messages onto---the port that Tomcat is using. You need to modify \gs\ to talk to port 8070 when it wants to talk to Tomcat, so that the messages go through TcpTunnelGui. This is specified in the \gst{<site>} element of the gateway site configuration file (\gst{\gsdlhome/web/sites/gateway/siteConfig.xml}). 2369 \begin{quote}\begin{gsc}\begin{verbatim} 2370 <site name="org.greenstone.localsite" 2371 address="http://localhost:8080/soap/servlet/rpcrouter" 2372 type="soap"/> 2373 \end{verbatim}\end{gsc}\end{quote} 2374 2375 Note that \gst{http://localhost:8080/soap/servlet/rpcrouter} is the 2376 address for talking to the Tomcat SOAP servlet services. 2377 2332 The listen port is the port that you want the monitor to be listening on. It should 'act as' a Listener, with target hostname 127.0.0.1 (localhost), and target port the port that Tomcat is running on (8080). You need to modify the address used to talk to the SOAP service. For example, if you want to monitor traffic between the gateway site and the localsite SOAP server, you will need to edit gateway's siteConfig.xml file and change the port number (in the site element) to whatever you have chosen as the listen port. 2378 2333 2379 2334 \newpage
Note:
See TracChangeset
for help on using the changeset viewer.