Revision: 13817
http://gate.svn.sourceforge.net/gate/?rev=13817&view=rev
Author: ian_roberts
Date: 2011-05-09 22:37:05 +0000 (Mon, 09 May 2011)
Log Message:
-----------
Installation notes.
Added Paths:
-----------
teamware/trunk/doc/installation.html
teamware/trunk/doc/installation.yam
Added: teamware/trunk/doc/installation.html
===================================================================
--- teamware/trunk/doc/installation.html (rev 0)
+++ teamware/trunk/doc/installation.html 2011-05-09 22:37:05 UTC (rev
13817)
@@ -0,0 +1,234 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd";>
+<!-- AUTOGENERATED FILE: ALL EDITS WILL BE LOST!!! -->
+<html lang="en">
+<head>
+<meta name="generator" content="cow"/>
+<title>Installing GATE Teamware</title>
+<style type="text/css">
+/*<![CDATA[*/
+<!--
+html, body {
+ background: #fff;
+ color: #000;
+ font-family: sans-serif;
+}
+h1,h2,h3,h4,h5,p,ul,ol { font-family: sans-serif; }
+pre { font-family: monospace; }
+h3.navhead {
+ font-size: 100%;
+}
+div.banner {
+ border: none;
+ margin-right: 0px;
+ margin-left: 0px;
+ padding: 0.09em;
+ text-align: center;
+ font-weight: bold;
+}
+div.banner a:link, div.banner {
+ background: #A0D0F0;
+ color: #000000;
+}
+div.banner a:active {
+ background: #000000;
+ color: #FFFFFF;
+}
+div.banner a:hover {
+ background: #000000;
+ color: #FFFFFF;
+-->
+/*]]>*/
+</style>
+</head>
+<body bgcolor="#FFFFFF" text="#000000">
+<h1 class="cow-title-heading">Installing GATE Teamware</h1>
+
+<div class="cow-contents"><h2 class="cow-heading">Contents</h2>
+<p><ul>
+<li><a href="#section-1.">1. Introduction</a></li>
+<li><a href="#section-2.">2. Requirements</a></li>
+<li><a href="#section-3.">3. Building the installer</a></li>
+<li><a href="#section-4.">4. Installing Teamware</a></li>
+<li><a href="#section-5.">5. Customizing the installer build</a></li>
+<li> <a href="#section-5.1.">5.1. Code signing</a></li>
+<li> <a href="#section-5.2.">5.2. Configuring Teamware for
HTTPS</a></li>
+</ul></p></div>
+<a class="cow-section-anchor" name="section-1."></a><h1
class="cow-heading"><span class="cow-sec-number">1. </span>Introduction</h1>
+
+<p>While the bundled tomcat6 is useful for running GATE Teamware in development
+mode, in production systems you will probably need to deploy Teamware to a
+standalone server. The "dist" target in the top-level Teamware
build file
+produces a graphical installer that can be used to install teamware into an
+existing Tomcat and MySQL setup, and the following sections of this document
+describe the requirements that must be in place on the production server before
+deploying Teamware, and the installation process itself.</p>
+<a class="cow-section-anchor" name="section-2."></a><h1
class="cow-heading"><span class="cow-sec-number">2. </span>Requirements</h1>
+
+<p>A server that will be hosting GATE Teamware requires the following:</p>
+
+<ul>
+<li>A recent Java 6 JDK (Sun/Oracle or OpenJDK), 1.6.0<span
class="cow-escape">_</span>14 or later.</li>
+<li>An installation of Apache Tomcat 6 (Teamware should work with any Tomcat of
+ version 5.5 or later but has been tested only with 6.0.x).
+ <ul>
+ <li>To work with the installer, the server configuration must use the default
+ <Engine> name "Catalina" and the default <Host> name
"localhost". If your
+ tomcat does not use these names manual intervention will be required after
+ the installer is run to rename the configuration files.</li>
+ </ul></li>
+<li>A MySQL server, with a user account that has been granted "ALL
PRIVILEGES" on
+ a database. The installer will create and populate this database during
+ Teamware installation.</li>
+<li>A directory to store the non-database persistent data for Teamware, which
+ must be readable and writeable by the user account under which the Tomcat
+ server runs. The doc-service searchable datastore is stored here, which
+ requires disk space up to ten times the total size of the documents stored.
+ On a development system this defaults to ~/safe/{instancename}.</li>
+</ul>
+
+<p>The various components of Teamware need to communicate with one another at
+runtime, so if your Tomcat is running behind a front-end proxy (typically
+Apache HTTPD) then it is useful to configure a second non-proxy-aware
+<Connector> in the Tomcat configuration so this inter-service
communication can
+go direct to localhost rather than having to go through the proxy server. This
+is especially important if the front-end proxy uses SSL.</p>
+<a class="cow-section-anchor" name="section-3."></a><h1
class="cow-heading"><span class="cow-sec-number">3. </span>Building the
installer</h1>
+
+<p>To build the GATE Teamware installer, start with a fresh checkout of the
+relevant version of the Teamware source code. It is especially important that
+the <tt>tomcat6</tt> directory is <em>completely</em> clean and does not have
any left-over
+<tt><em>anything</em>-webapps</tt> directories or
<tt>conf/Catalina/localhost</tt> configuration
+files.</p>
+
+<p>To build an installer for the default "cloud-tw" installation of
GATE Teamware,
+run:</p>
+
+<pre>
+ant -propertyfile install.properties dist
+</pre>
+
+<p>The installer will be placed in dist/install.jar. To build an installer
for an
+installation other than the default cloud-tw, you need to provide additional
+system property definitions to ant. For the installation specified in
+<tt>installations/myinstance</tt>, specify
<tt>-Ddefault.instance.name=myinstance</tt>. For
+an installation specified by an instance directory that is <em>not</em> under
the
+<tt>installations</tt> directory you must additionally specify
+<tt>-Ddefault.instance.project.dir=/path/to/myinstance</tt>. Note that this is
+different from installing a non-default instance into the bundled tomcat6 -
+when building the installer you <b>must not</b> provide
<tt>-Dinstance.name=...</tt>, as
+the installer build uses a special dummy value for this property.</p>
+<a class="cow-section-anchor" name="section-4."></a><h1
class="cow-heading"><span class="cow-sec-number">4. </span>Installing
Teamware</h1>
+
+<p>To install GATE Teamware, copy the generated install.jar to the production
+server and run it (using java -jar) as a user that has write permission to the
+Tomcat directory and the intended data directory. This will present a
+graphical installer which will prompt you for various settings. The first page
+asks for:</p>
+
+<ul>
+<li>The location of your Tomcat installation. This is the top directory, i.e.
+ the parent of of bin, conf, webapps, etc.</li>
+<li>The instance name for the target installation. Obviously, the services and
+ settings installed will be those for the installation that was specified when
+ the installer was built, but this option allows you to configure the context
+ path under which the Teamware web applications will be deployed. For
+ example, setting this to "customtw" will make the executive
available at
+ <span
class="cow-escape">h</span>ttp://someserver.com/customtw/executive/</li>
+<li>The data directory described above, where the datastore and other
+ non-database persistent data will be stored.</li>
+</ul>
+
+<p>The second page asks for the public and private <em>URL base</em> patterns.
These are
+the protocol, host and possibly port number at which your Teamware will be
+visible, and must match the values configured for the Tomcat server. The
+public URL base is the URL which remote users will use to connect to Teamware.
+For a standalone Tomcat this would be something like
+<tt><span class="cow-escape">h</span>ttp://teamware.example.com:8080</tt>, for
a Tomcat which is behind a front-end
+Apache HTTPD it might be <tt><span
class="cow-escape">h</span>ttp://teamware.example.com</tt> or
+<tt><span class="cow-escape">h</span>ttps://secure.example.com</tt>. The URL
base <em>must not</em> have a trailing slash.</p>
+
+<p>The <em>private</em> URL base is the URL that the teamware services use to
talk to one
+another, and will typically be <tt><span
class="cow-escape">h</span>ttp://localhost:8080</tt> (or whatever port
+number the non-proxied <Connector> is set to use). If in doubt, use the
same
+value as for the public URL base.</p>
+
+<p>The third page asks for the settings that Teamware should use to send out
+notification emails to users, and the fourth page asks for details of the MySQL
+database that Teamware should use. As mentioned above, the username/password
+combination you supply here must have ALL PRIVILEGES on the specified database
+for the installer to be able to create the database schema. You may be able to
+restrict these privileges somewhat once Teamware is up and running but this is
+not something that has been extensively tested.</p>
+
+<p>The final page allows you to choose a custom logo and title to brand your
+Teamware installation.</p>
+
+<p>Once all options have been set, the installer will install the Teamware web
+applications into your Tomcat, create the schema and install the initial data
+into MySQL, and seed the persistent data directory with initial annotation
+schemas, etc.</p>
+
+<p>After the installation is complete you may need to change the permissions
+and/or ownership of the persistent data directory, if you ran the installer as
+a different user from the one that will be used to run Tomcat.</p>
+<a class="cow-section-anchor" name="section-5."></a><h1
class="cow-heading"><span class="cow-sec-number">5. </span>Customizing the
installer build</h1>
+
+<p>There are a number of things you may wish to customize when building the
+installer. Using a non-default Teamware installation as the base for the
+installer has been described above. The other common customizations are to use
+a custom code signing certificate for the Java Web Start JAR files, and to
+configure Teamware to be able to run over https.</p>
+<a class="cow-section-anchor" name="section-5.1."></a><h2
class="cow-heading"><span class="cow-sec-number">5.1. </span>Code signing</h2>
+
+<p>GATE Teamware includes a number of Java Web Start applications, most notably
+the manual annotation GUI. For Java Web Start all the JAR files in the
+application must be cryptographically signed, and when the user runs the app
+they will be prompted to trust the signing certificate, and warned if the
+certificate is not trusted or has expired. If you are deploying Teamware in an
+enterprise where you already use code signing for other applications you may
+wish to sign the Teamware JWS applications with an existing trusted
+certificate.</p>
+
+<p>To do this, you need the private key and certificate in a JKS-format Java
+keystore (see the keytool documentation for details). The keystore must also
+contain the chain of certificates from the issuer of the signing certificate up
+to the relevant CA root certificate. The following ant properties are used to
+direct the build to use your signing certificate instead of the default
one:</p>
+
+<ul>
+<li><tt>keystore</tt> - the absolute path to the keystore file containing the
signing
+ key and certificate.</li>
+<li><tt>alias</tt> - the alias of the signing key (i.e. its identifier in the
keystore).</li>
+<li><tt>storepass</tt> and <tt>keypass</tt> - the passphrases protecting the
keystore itself
+ and the key within the store respectively.</li>
+</ul>
+
+<p>You can either specify these properties using <tt>-D</tt> command line
options when
+running ant, or by putting them in a properties file and pointing ant to that
+file using a second <tt>-propertyfile</tt> argument.</p>
+<a class="cow-section-anchor" name="section-5.2."></a><h2
class="cow-heading"><span class="cow-sec-number">5.2. </span>Configuring
Teamware for HTTPS</h2>
+
+<p>The web service toolkit used by the various Teamware components to talk to
the
+back-end services is able to communicate with https endpoints, but unlike a
+regular web browser it does not trust any https server certificates by default.
+Thus if your public URL base is an https URL, you need to provide configuration
+when building the installer in order to allow the manual annotation GUI to
+trust your server.</p>
+
+<p>To do this, you must create a JKS keystore file containing the certificate
of
+the root CA that is the ultimate issuer of your https server's certificate
+(i.e. if your certificate was signed by an intermediate authority A and that
+certificate was issued by a root authority B then it is B's certificate you
+need, not A's). This keystore must have a passphrase set but as the store
+should contain only trusted certificate entries (no private keys) this need not
+be a secure password - "password" or "changeit" is
perfectly adequate.</p>
+
+<p>To point the build at this keystore, use the following system properties (as
+<tt>-D</tt> options or in a propertyfile as described above):</p>
+
+<ul>
+<li><tt>https.truststore</tt> - the absolute path to the keystore file</li>
+<li><tt>https.truststore.password</tt> - the keystore password</li>
+</ul>
+</body></html>
Added: teamware/trunk/doc/installation.yam
===================================================================
--- teamware/trunk/doc/installation.yam (rev 0)
+++ teamware/trunk/doc/installation.yam 2011-05-09 22:37:05 UTC (rev 13817)
@@ -0,0 +1,177 @@
+Installing GATE Teamware
+
+%contents
+
+%1 Introduction
+
+While the bundled tomcat6 is useful for running GATE Teamware in development
+mode, in production systems you will probably need to deploy Teamware to a
+standalone server. The "dist" target in the top-level Teamware build file
+produces a graphical installer that can be used to install teamware into an
+existing Tomcat and MySQL setup, and the following sections of this document
+describe the requirements that must be in place on the production server before
+deploying Teamware, and the installation process itself.
+
+%1 Requirements
+
+A server that will be hosting GATE Teamware requires the following:
+
+- A recent Java 6 JDK (Sun/Oracle or OpenJDK), 1.6.0\_14 or later.
+- An installation of Apache Tomcat 6 (Teamware should work with any Tomcat of
+ version 5.5 or later but has been tested only with 6.0.x).
+ - To work with the installer, the server configuration must use the default
+ <Engine> name "Catalina" and the default <Host> name "localhost". If your
+ tomcat does not use these names manual intervention will be required after
+ the installer is run to rename the configuration files.
+- A MySQL server, with a user account that has been granted "ALL PRIVILEGES" on
+ a database. The installer will create and populate this database during
+ Teamware installation.
+- A directory to store the non-database persistent data for Teamware, which
+ must be readable and writeable by the user account under which the Tomcat
+ server runs. The doc-service searchable datastore is stored here, which
+ requires disk space up to ten times the total size of the documents stored.
+ On a development system this defaults to ~/safe/{instancename}.
+
+The various components of Teamware need to communicate with one another at
+runtime, so if your Tomcat is running behind a front-end proxy (typically
+Apache HTTPD) then it is useful to configure a second non-proxy-aware
+<Connector> in the Tomcat configuration so this inter-service communication can
+go direct to localhost rather than having to go through the proxy server. This
+is especially important if the front-end proxy uses SSL.
+
+%1 Building the installer
+
+To build the GATE Teamware installer, start with a fresh checkout of the
+relevant version of the Teamware source code. It is especially important that
+the ^tomcat6^ directory is _completely_ clean and does not have any left-over
+^_anything_-webapps^ directories or ^conf/Catalina/localhost^ configuration
+files.
+
+To build an installer for the default "cloud-tw" installation of GATE Teamware,
+run:
+
+%<
+ant -propertyfile install.properties dist
+%>
+
+The installer will be placed in dist/install.jar. To build an installer for an
+installation other than the default cloud-tw, you need to provide additional
+system property definitions to ant. For the installation specified in
+^installations/myinstance^, specify ^-Ddefault.instance.name=myinstance^. For
+an installation specified by an instance directory that is _not_ under the
+^installations^ directory you must additionally specify
+^-Ddefault.instance.project.dir=/path/to/myinstance^. Note that this is
+different from installing a non-default instance into the bundled tomcat6 -
+when building the installer you *must not* provide ^-Dinstance.name=...^, as
+the installer build uses a special dummy value for this property.
+
+%1 Installing Teamware
+
+To install GATE Teamware, copy the generated install.jar to the production
+server and run it (using java -jar) as a user that has write permission to the
+Tomcat directory and the intended data directory. This will present a
+graphical installer which will prompt you for various settings. The first page
+asks for:
+
+- The location of your Tomcat installation. This is the top directory, i.e.
+ the parent of of bin, conf, webapps, etc.
+- The instance name for the target installation. Obviously, the services and
+ settings installed will be those for the installation that was specified when
+ the installer was built, but this option allows you to configure the context
+ path under which the Teamware web applications will be deployed. For
+ example, setting this to "customtw" will make the executive available at
+ \http://someserver.com/customtw/executive/
+- The data directory described above, where the datastore and other
+ non-database persistent data will be stored.
+
+The second page asks for the public and private _URL base_ patterns. These are
+the protocol, host and possibly port number at which your Teamware will be
+visible, and must match the values configured for the Tomcat server. The
+public URL base is the URL which remote users will use to connect to Teamware.
+For a standalone Tomcat this would be something like
+^\http://teamware.example.com:8080^, for a Tomcat which is behind a front-end
+Apache HTTPD it might be ^\http://teamware.example.com^ or
+^\https://secure.example.com^. The URL base _must not_ have a trailing slash.
+
+The _private_ URL base is the URL that the teamware services use to talk to one
+another, and will typically be ^\http://localhost:8080^ (or whatever port
+number the non-proxied <Connector> is set to use). If in doubt, use the same
+value as for the public URL base.
+
+The third page asks for the settings that Teamware should use to send out
+notification emails to users, and the fourth page asks for details of the MySQL
+database that Teamware should use. As mentioned above, the username/password
+combination you supply here must have ALL PRIVILEGES on the specified database
+for the installer to be able to create the database schema. You may be able to
+restrict these privileges somewhat once Teamware is up and running but this is
+not something that has been extensively tested.
+
+The final page allows you to choose a custom logo and title to brand your
+Teamware installation.
+
+Once all options have been set, the installer will install the Teamware web
+applications into your Tomcat, create the schema and install the initial data
+into MySQL, and seed the persistent data directory with initial annotation
+schemas, etc.
+
+After the installation is complete you may need to change the permissions
+and/or ownership of the persistent data directory, if you ran the installer as
+a different user from the one that will be used to run Tomcat.
+
+%1 Customizing the installer build
+
+There are a number of things you may wish to customize when building the
+installer. Using a non-default Teamware installation as the base for the
+installer has been described above. The other common customizations are to use
+a custom code signing certificate for the Java Web Start JAR files, and to
+configure Teamware to be able to run over https.
+
+%2 Code signing
+
+GATE Teamware includes a number of Java Web Start applications, most notably
+the manual annotation GUI. For Java Web Start all the JAR files in the
+application must be cryptographically signed, and when the user runs the app
+they will be prompted to trust the signing certificate, and warned if the
+certificate is not trusted or has expired. If you are deploying Teamware in an
+enterprise where you already use code signing for other applications you may
+wish to sign the Teamware JWS applications with an existing trusted
+certificate.
+
+To do this, you need the private key and certificate in a JKS-format Java
+keystore (see the keytool documentation for details). The keystore must also
+contain the chain of certificates from the issuer of the signing certificate up
+to the relevant CA root certificate. The following ant properties are used to
+direct the build to use your signing certificate instead of the default one:
+
+- ^keystore^ - the absolute path to the keystore file containing the signing
+ key and certificate.
+- ^alias^ - the alias of the signing key (i.e. its identifier in the keystore).
+- ^storepass^ and ^keypass^ - the passphrases protecting the keystore itself
+ and the key within the store respectively.
+
+You can either specify these properties using ^-D^ command line options when
+running ant, or by putting them in a properties file and pointing ant to that
+file using a second ^-propertyfile^ argument.
+
+%2 Configuring Teamware for HTTPS
+
+The web service toolkit used by the various Teamware components to talk to the
+back-end services is able to communicate with https endpoints, but unlike a
+regular web browser it does not trust any https server certificates by default.
+Thus if your public URL base is an https URL, you need to provide configuration
+when building the installer in order to allow the manual annotation GUI to
+trust your server.
+
+To do this, you must create a JKS keystore file containing the certificate of
+the root CA that is the ultimate issuer of your https server's certificate
+(i.e. if your certificate was signed by an intermediate authority A and that
+certificate was issued by a root authority B then it is B's certificate you
+need, not A's). This keystore must have a passphrase set but as the store
+should contain only trusted certificate entries (no private keys) this need not
+be a secure password - "password" or "changeit" is perfectly adequate.
+
+To point the build at this keystore, use the following system properties (as
+^-D^ options or in a propertyfile as described above):
+
+- ^https.truststore^ - the absolute path to the keystore file
+- ^https.truststore.password^ - the keystore password
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Achieve unprecedented app performance and reliability
What every C/C++ and Fortran developer should know.
Learn how Intel has extended the reach of its next-generation tools
to help boost performance applications - inlcuding clusters.
http://p.sf.net/sfu/intel-dev2devmay
_______________________________________________
GATE-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/gate-cvs
