Changeset 9843 for branches/ant-install-branch/gsdl3

Timestamp:

2005-05-09T12:01:56+12:00 (19 years ago)

Author:

kjdon

Message:

updated to reflect new ant installation process

Location:

branches/ant-install-branch/gsdl3/docs/manual

Files:

• manual.pdf (modified) ( previous)
• manual.tex (modified) (15 diffs)

branches/ant-install-branch/gsdl3/docs/manual/manual.tex

@@ -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. 
 
+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.
 
 \subsection{Get and install \gs\ }
@@ -75 +76 @@
 \subsubsection{Linux}
 
-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).
+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).
 
 \subsubsection{Windows}
 
-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.
+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).
 
 \subsubsection{Accessing the library in a browser}\label{sec:browser-access}
@@ -93 +94 @@
 \subsubsection{Restarting the library}
 
-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}.
+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}.
 
 
@@ -366 +367 @@
 \begin{figure}[h]
   \centering
-  \includegraphics[width=4in]{pagebanner} %5.8
+  \includegraphics[width=4in]{pagebanner.ps} %5.8
   \caption{A sample collection page banner}
   \label{fig:page-banner}
@@ -389 +390 @@
 
 To create the director
-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. 
+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. 
 
 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}.
 
-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.
+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.
 
 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]
   \centering
-  \includegraphics[width=4in]{newlocal} %5.8
+  \includegraphics[width=4in]{local} %5.8
   \caption{A simple stand-alone site.}
   \label{fig:local}
@@ -2176 +2177 @@
 \end{figure}
 
-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}.
+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}.
 
 \subsection{Serving a site using soap}
 
-A script has been created to setup a SOAP server for a site. On Linux, from the gsdl3 directory, run
-\gst{./gs3-soap-deploy-site.sh <sitename> <siteuri>}
-
-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.
-
-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}.
+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.
+
+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}.
 
 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}
 <site name="siteAuri"
-  address="http://localhost:8080/soap/servlet/rpcrouter"
+  address="http://localhost:8080/axis/services/siteAuri"
   type="soap"/>
 \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. 
 
-Note that you will need the Java 2 SDK, version 1.4.0 or higher.
+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.
 
 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. 
 
-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.
-
-To install Greenstone once you have checked it out of CVS, do the following (alternatives for Linux or Windows):
+Greenstone is built and installed using Ant (Apache's Java based build tool, 
+http://ant.apache.org). You will need a Java Development 
+Environment (1.4 or higher), and Ant installed to use Greenstone. You can download Ant from http://ant.apache.org/bindownload.cgi.
+
+In the gsdl3 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, startup the server etc.
+
+For a first time install, run 'ant install'.
+
+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.
+For a  non-interactive version of the install, run
+ant -Dproperties.accepted=yes install
+
+To log the output in build.log, run
+ant -Dproperties.accepted=yes -logfile build.log install
+
+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.)
+
+
+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. 
+
+To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are (run from the gsdl3 directory):
 
 \begin{quote}\begin{gsc}
-cd gsdl3\\
-./gs3-install.sh or gs3-install\\
-source gs3-setup.sh or gs3-setup
+ant start \\
+ant stop
 \end{gsc}\end{quote}
 
-To recompile the code at any stage, you can use
-\begin{quote}\begin{gsc}
-source gs3-setup.sh or gs3-setup\\
-make\\
-make install\\
-\end{gsc}\end{quote}
-
-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. 
-
-To startup or shutdown the library (includes the Tomcat server and MYSQL server), the commands are (run from the gsdl3 directory):
-\begin{quote}\begin{gsc}
-./gs3-launch.sh or gs3-launch \\
-./gs3-launch.sh -shutdown or close the window
-\end{gsc}\end{quote}
-
+If you want to restart only Tomcat, run \gst{ant restart-tomcat}.
 
 \newpage
 \section{Tomcat}\label{app:tomcat}
 
-Tomcat is a servlet container. It is used to serve a \gs\  site using a servlet.
+Tomcat is a servlet container, and Greenstone 3 runs as a servlet inside it. 
 
 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 @@
 
 
-Tomcat runs by default on port 8080---this can be changed in server.xml, in the \begin{quote}\begin{gsc}
-<!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8080 -->\\
-<Connector>
-\end{gsc}\end{quote}
- 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.
+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.
 
 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}
 \item \gsdlhome/web/WEB-INF/web.xml
-\item \gsdlhome/comms/jakarta/tomcat-tomcat-4.0.1/conf/server.xml
+\item \gsdlhome/comms/jakarta/tomcat/conf/server.xml
 \end{gsc}
 \item any classes or jar files used by the servlets
 \end{bulletedlist}
-\noindent Note: stdin and stdout for the servlets both go to\\
+\noindent Note: stdin and stdout for the servlets (on linux) both go to\\
 \gst{\gsdlhome/comms/jakarta/tomcat/logs/catalina.out}
 
@@ -2282 +2281 @@
 \end{gsc}\end{quote}
 
-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}):
-
-In the default servlet definition, change the 'listings' parameter to true.
+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}):
 
 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}
 
-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:
-
-\begin{quote}\begin{gsc}
-gs3-enable-soap.[sh/bat]
-\end{gsc}\end{quote}
-
-All this does is to rename the SOAP web.xml.disabled file to web.xml. 
-
-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.
-
-To deploy a SOAP service for other sites, run
-\begin{quote}\begin{gsc}
-gs3-soap-deploy-site.[sh/bat] <sitename> <siteURI>
-\end{gsc}\end{quote}
-
-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:
-
-\begin{gsc}\begin{verbatim}
-java org.apache.soap.server.ServiceManagerClient 
-  http://localhost:8080/soap/servlet/rpcrouter deploy 
-  resources/soap/<sitename>.xml
-\end{verbatim}\end{gsc} 
-
-You can also deploy a service through the website.  If Tomcat is not running, start it up. 
-
-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.
-
-To deploy the SOAPServer for siteX:
-
-Click on ``deploy'' and edit the following fields in the deploy form:
-
-\begin{tabular}{ll}
-ID: & <URI for siteX>\\
-Scope: (choose Session  & Request---new instantiation for each request\\
-  or Application)   &    Session---same instantiation across a session\\
-        &    Application---only uses one instantiation\\
-Methods: &process\\
-Java Provider / Provider Class: & org.greenstone.gsdl3.SOAPServersiteX\\
-\end{tabular}
-
-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.
-
-Information about deployed services is maintained between Tomcat sessions---you only need to deploy it once. 
+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.
+
+To deploy a SOAP service for other sites, run \gst{ant soap-deploy-site}
+
+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.
+
+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}.
+
+The axis servlet can be accessed at \gst{localhost:8080/axis}.
 
 \subsection{Debugging SOAP}\label{app:soap-debug}
 
-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.
+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.
 To run it, type:
 
-\begin{quote}\gst{java org.apache.soap.util.net.TcpTunnelGui 8070 localhost 8080}
+\begin{quote}\gst{java -cp <path to gsdl3>/comms/soap/axis/lib/axis.jar \\
+org.apache.axis.utils.tcpmon}
 \end{quote}
 
-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}). 
-\begin{quote}\begin{gsc}\begin{verbatim}
-<site name="org.greenstone.localsite" 
-      address="http://localhost:8080/soap/servlet/rpcrouter" 
-      type="soap"/>
-\end{verbatim}\end{gsc}\end{quote}
-
-Note that \gst{http://localhost:8080/soap/servlet/rpcrouter} is the
-address for talking to the Tomcat SOAP servlet services.
-
+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.
 
 \newpage