| ------ |
| Guide to Install Continuum on Tomcat |
| ------ |
| Joakim Erdfelt |
| Emmanuel Venisse |
| ------ |
| 2008-09-01 |
| ------ |
| |
| Guide to Install Continuum on Tomcat |
| |
| Instructions for installing, deploying, configuring Continuum for the Apache Tomcat web container. |
| |
| Sections: |
| |
| ~~%{toc|section=0} |
| |
| * {Basics & Fundamentals} |
| |
| With every Tomcat version you will need a few things before you can deploy Continuum. |
| |
| [[1]] Use at least Java JDK 1.5.0_11 to run Tomcat w/Continuum. |
| |
| [[1]] A defined \<Context\> xml section to define the JNDI resources. |
| |
| [[1]] The JavaMail / Activation JAR files. |
| |
| [[1]] The Apache Derby JAR files. |
| |
| [[1]] Configure $\{appserver.base\} java property. |
| |
| ** {Defining JNDI Resources}. |
| |
| Continuum will, on startup, ask the web container for a few JNDI configured resources, two JDBC DataSources, and one JavaMail session. |
| |
| To configure these JNDI resources in the Tomcat Web Container, you will need to specify a \<Context\> section that Tomcat can utilize for those requests coming from Continuum. |
| |
| Tomcat has 3 main ways to accomplish this (ordered by most recommended to least recommended) |
| |
| [[1]] Creating a $CATALINA_HOME/webapps/continuum/META-INF/context.xml containing a \<Context\> element. |
| |
| [[1]] Creating a $CATALINA_HOME/conf/Catalina/localhost/continuum.xml containing a \<Context\> element. |
| |
| [[1]] Adding a \<Context\> Section into the $CATALINA_HOME/conf/server.xml |
| |
| The following are the JNDI names you will need to provide: |
| |
| * <<<mail/Session>>> |
| |
| * <<<jdbc/continuum>>> |
| |
| * <<<jdbc/users>>> |
| |
| The individual techniques for describing these resources, and the parameters associated with them are specific to the Tomcat version, resource type, and even JDBC implementation type. |
| |
| For the purposes of this document, the following assumptions are made. |
| |
| [[1]] You are an Apache Tomcat administrator. |
| |
| [[1]] You have an SMTP Server on localhost, port 25, with no login / password. |
| |
| [[1]] You will be using the embedded Apache Derby database. (not an external database, that's another show) |
| |
| [[1]] Details specific to Apache Tomcat, JavaMail, or Apache Derby are left for the reader to research on those projects websites. |
| |
| ** {The JavaMail / Activation JAR files} |
| |
| <<Note:>> Continuum requires JavaMail 1.4 (or later) |
| |
| Apache Tomcat does not typically ship with a copy of the JavaMail or Activation jar files. |
| In your role as the Apache Tomcat administrator of your installation, you will need to obtain these jar files and place it into your preferred lib directory. |
| |
| The appropriate lib directory to choose is a personal preference, and we do not encourage or enforce a specific location for it, as all installations of Apache Tomcat are different. |
| |
| For the record, we personally put them in the <<<$CATALINA_HOME/common/lib/>>> directory. |
| |
| Direct download links for these jar files. |
| |
| * JavaMail 1.4 - {{{http://repo1.maven.org/maven2/javax/mail/mail/1.4/mail-1.4.jar}mail-1.4.jar}} |
| |
| * Java Activation Framework 1.1 - {{{http://repo1.maven.org/maven2/javax/activation/activation/1.1/activation-1.1.jar}activation-1.1.jar}} |
| |
| ** {The Apache Derby JAR files} |
| |
| <<Note:>>Continuum 1.2 has been tested with Apache Derby 10.1.3.1 |
| |
| The default installation of Continuum uses the Apache Derby 100% Java database to maintain Continuum-specific information, and also the Users / Security Database. |
| |
| You will need to obtain the derby.jar and derbytools.jar and place them into your preferred lib directory. |
| |
| We put them into the <<<$CATALINA_HOME/common/lib/>>> directory. |
| |
| Direct download links for these jar files: |
| |
| * {{{http://repo1.maven.org/maven2/org/apache/derby/derby/10.1.3.1/derby-10.1.3.1.jar}derby-10.1.3.1.jar}} |
| |
| * {{{http://repo1.maven.org/maven2/org/apache/derby/derbytools/10.1.3.1/derbytools-10.1.3.1.jar}derbytools-10.1.3.1.jar}} |
| |
| ** {Configure the appserver.base java property} |
| |
| The <<<$\{appserver.base\}>>> java property is used by the Continuum internal logging configuration to determine where to output its logs to. |
| It is important to define this property either in the <<<$CATALINA_OPTS>>> system environment variable (if Tomcat is being launched via |
| the command line) or the service properties (if being launched as a service or daemon). |
| |
| The format typically expected is <<<\-Dappserver.base=\<SOMEWHERE\>>>> |
| |
| You can utilize the <<<$CATALINA_HOME/bin/setenv.sh>>> script to set this value in a tomcat specific way. |
| |
| ------------------------------------------ |
| #!/bin/bash |
| # Keep the appserver.home and appserver.base values the same when running under Tomcat |
| |
| export CATALINA_OPTS="-Dappserver.home=$CATALINA_HOME -Dappserver.base=$CATALINA_HOME" |
| ------------------------------------------ |
| |
| * {Tomcat 5.0.x Specifics} |
| |
| Tested on Tomcat v5.0.28 |
| |
| These instructions explain how to deploy the Continuum 1.2 web application in an existing installation of Tomcat 5.0.x. |
| |
| <<Extra Jars:>> |
| |
| * You will need the {{{http://repo1.maven.org/maven2/xalan/xalan/2.7.0/xalan-2.7.0.jar}xalan-2.7.0.jar}} copied into your <<<$CATALINA_HOME/common/lib/>>> directory. |
| |
| * The Xerces XML Implementation provided in Tomcat 5.0.x is old and will cause problems with Continuum and |
| the internal JAXP implementation in JDK 1.5, we recommend that you remove the files in <<<$CATALINA_HOME/common/endorsed/>>>. |
| |
| ------------------------------------------ |
| <Context path="/continuum" docBase="/path/to/continuum-webapp-1.2.war" debug="0"> |
| |
| <!-- JNDI Datasource for User/Security Database (REQUIRED) --> |
| <Resource name="jdbc/users" auth="Container" type="javax.sql.DataSource"/> |
| <ResourceParams name="jdbc/users"> |
| <parameter> |
| <name>driverClassName</name> |
| <value>org.apache.derby.jdbc.EmbeddedDriver</value> |
| </parameter> |
| <parameter> |
| <name>factory</name> |
| <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> <!-- Sets up Database Connection Pooling --> |
| </parameter> |
| <parameter> |
| <name>url</name> |
| <value>jdbc:derby:database/users;create=true</value> <!-- Adjust path to suit --> |
| </parameter> |
| <parameter> |
| <name>username</name> |
| <value>sa</value> |
| </parameter> |
| <parameter> |
| <name>password</name> |
| <value></value> |
| </parameter> |
| </ResourceParams> |
| |
| <!-- JNDI Datasource for Continuum Database (REQUIRED) --> |
| <Resource name="jdbc/continuum" auth="Container" type="javax.sql.DataSource"/> |
| <ResourceParams name="jdbc/continuum"> |
| <parameter> |
| <name>driverClassName</name> |
| <value>org.apache.derby.jdbc.EmbeddedDriver</value> |
| </parameter> |
| <parameter> |
| <name>factory</name> |
| <value>org.apache.commons.dbcp.BasicDataSourceFactory</value> <!-- Sets up Database Connection Pooling --> |
| </parameter> |
| <parameter> |
| <name>url</name> |
| <value>jdbc:derby:database/continuum;create=true</value> <!-- Adjust path to suit --> |
| </parameter> |
| <parameter> |
| <name>username</name> |
| <value>sa</value> |
| </parameter> |
| <parameter> |
| <name>password</name> |
| <value></value> |
| </parameter> |
| </ResourceParams> |
| |
| <Resource name="mail/Session" auth="Container" type="javax.mail.Session"/> |
| <ResourceParams name="mail/Session"> |
| <parameter> |
| <name>mail.smtp.host</name> |
| <value>localhost</value> |
| </parameter> |
| </ResourceParams> |
| </Context> |
| ------------------------------------------ |
| |
| * {Tomcat 5.5.x Specifics} |
| |
| Tested on Tomcat v5.5.17 and v5.5.25 |
| |
| This example \<Context\> assumes technique #2 in the {{{#Defining_JNDI_Resources}Define JNDI Resource}} list. (This example lists out the <<<docBase>>> to the war file itself.) |
| |
| ------------------------------------------ |
| <Context path="/continuum" |
| docBase="/path/to/continuum-webapp-1.2.war"> |
| |
| <Resource name="jdbc/users" |
| auth="Container" |
| type="javax.sql.DataSource" |
| username="sa" |
| password="" |
| driverClassName="org.apache.derby.jdbc.EmbeddedDriver" |
| url="jdbc:derby:database/users;create=true" /> |
| |
| <Resource name="jdbc/continuum" |
| auth="Container" |
| type="javax.sql.DataSource" |
| username="sa" |
| password="" |
| driverClassName="org.apache.derby.jdbc.EmbeddedDriver" |
| url="jdbc:derby:database/continuum;create=true" /> |
| |
| <Resource name="mail/Session" |
| auth="Container" |
| type="javax.mail.Session" |
| mail.smtp.host="localhost"/> |
| </Context> |
| ------------------------------------------ |
| |
| <<Warning:>> The Tomcat 5.5.20 and 5.5.23 releases are missing MailSessionFactory and a few other classes. |
| JNDI mail sessions will <<not>> work. Use Tomcat 5.5.17 or see the workaround on {{{http://issues.apache.org/bugzilla/show_bug.cgi?id=40668}Bug 40668}}. |
| |
| * {Tomcat 6.0.x Specifics} |
| |
| Tested on Tomcat v6.0.14 |
| |
| ------------------------------------------ |
| <Context path="/continuum" |
| docBase="/path/to/continuum-webapp-1.2.war"> |
| |
| <Resource name="jdbc/users" |
| auth="Container" |
| type="javax.sql.DataSource" |
| username="sa" |
| password="" |
| driverClassName="org.apache.derby.jdbc.EmbeddedDriver" |
| url="jdbc:derby:database/users;create=true" /> |
| |
| <Resource name="jdbc/continuum" |
| auth="Container" |
| type="javax.sql.DataSource" |
| username="sa" |
| password="" |
| driverClassName="org.apache.derby.jdbc.EmbeddedDriver" |
| url="jdbc:derby:database/continuum;create=true" /> |
| |
| <Resource name="mail/Session" |
| auth="Container" |
| type="javax.mail.Session" |
| mail.smtp.host="localhost"/> |
| </Context> |
| ------------------------------------------ |