Deploying Cosmo in Tomcat

See CosmoServletContainerRequirements for the general set of expectations the Cosmo webapp has for a servlet container. This document describes how to meet those expectations with Tomcat. It assumes familiarity with configuring Tomcat and deploying web applications into the server.

Cosmo has only been tested with Tomcat 5.5.

Installation instructions

These instructions are for Unix-like systems, but the modifications for Windows should be obvious. Filesystem paths within the Tomcat installation are prefixed with $CATALINA_HOME. Relative filesystem paths refer to the base directory of the unpacked Cosmo webapp tarball.

1. Download and unpack osaf-server-bundle-x.y.z
2. Create a database (see CosmoDatabaseSetup).
3. Install (or make sure you already have) the API dependencies (see CosmoServletContainerRequirements)
4. Check that your Logging is setup to use log4j.
5. Copy etc/cosmo.properties to a convenient location (e.g. /etc/tomcat/ or $CATALINA_HOME/conf/). Note that you must edit this file and set the SQL dialect to the database of your choice. (TODO this external properties file business is a pain... would be good to set everything in the XML file)
6. Setup the context (see Context configuration below).
7. Set $JAVA_OPTS in the Tomcat user's environment (see CosmoStartupConfiguration) . (TODO this is totally uncalled for... servlets should never ever ever need the container to set global properties!!)
8. Set the security permissions (see Security below).
9. Copy cosmo-x.y.z.war into Tomcat's application base directory, renaming it to chandler.war ($CATALINA_HOME/webapps by default).
10. Ensure that all Connector elements in your $CATALINA_HOME/conf/server.xml file have the attribute URIEncoding="UTF-8". Cosmo allows UTF-8 characters in usernames, and it often includes usernames in its URIs. (TODO forcing all servlets to use a setting is bad)
11. Restart Tomcat.

Context configuration

The preferred way to configure a web applications in Tomcat is by dropping a context config file into $CATALINA_HOME/conf/{engine}/{host}/, where {engine} is the name of the <Engine> configured in server.xml, {host} is the name of the <Host> in server.xml. The config file must be named exactly the same as the WAR file or exploded directory when it is deployed, except with a .xml extension. For example, if the Cosmo WAR is named chandler.war, the context config file must be named chandler.xml.

A typical $CATALINA_HOME/conf/{engine}/{host}/chandler.xml file might look something like

<?xml version="1.0" encoding="UTF-8"?>
<Context reloadable="false">
        <Valve className="org.apache.catalina.valves.AccessLogValve"
                directory="../logs" prefix="access." suffix=".log"
                pattern="%h %l %{COSMO_PRINCIPAL}r %t &quot;%r&quot; %s %b &quot;%{Referer}i&quot; &quot;%{User-Agent}i&quot;"
                resolveHosts="false"/>
        <Environment name="cosmo/config" value="file:/sw/etc/tomcat5/cosmo.properties" type="java.lang.String" override="false"/>
        <Resource name="jdbc/cosmo"
                type="javax.sql.DataSource"
                username="cosmo"
                password="cosmo"
                driverClassName="org.postgresql.Driver"
                url="jdbc:postgresql://localhost:5432/cosmo"/>
        <Resource name="mail/cosmo"
                type="javax.mail.Session"
                mail.transport.protocol="smtp"
                mail.smtp.host="localhost"/>
</Context>

It provides an environment entry specifying the location (either filesystem or classpath) of the Cosmo configuration properties file, J2EE resources for the database and mail server, and an access logging valve that includes a custom Cosmo request attribute (TODO: doc this request attribute on the logging page). It also tells Tomcat not to monitor the WAR for changes.

For more information on configuring environment entries and resources, see http://tomcat.apache.org/tomcat-5.5-doc/jndi-resources-howto.html.

Logging

Tomcat does not come with support for commons-logging and log4j out of the box for servlets, so you must install the commons-logging and log4j jar files into your $CATALINA_HOME/common/libs folder (not the endorsed folder). You must also configure log4j once you install it or you won't see any debugging output at all. For Tomcat 5.5 please read Tomcat Logging to setup your system to handle commons-logging and log4j. The short version is that you must create a file named log4j.properties in your $CATALINA_HOME/common/classes folder with the following contents

log4j.rootLogger=WARN, R 
log4j.appender.R=org.apache.log4j.RollingFileAppender 
log4j.appender.R.File=${catalina.home}/logs/tomcat.log 
log4j.appender.R.MaxFileSize=10MB 
log4j.appender.R.MaxBackupIndex=10 
log4j.appender.R.layout=org.apache.log4j.PatternLayout 
log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=WARN, R
log4j.logger.org.apache.catalina.core=WARN, R
log4j.logger.org.apache.catalina.session=WARN, R

log4j.logger.org.osaf.cosmo=DEBUG

That gets you a default logging setup that will log everything to $CATALINA_HOME/logs/tomcat.log.

TODO output Chandler logging to a separate file.

Security

Depending on how strict your security policy is, you may need to allow the following permissions in your policy scripts (paths and database paths may need editing for your site)

grant codeBase "file:/var/lib/tomcat5.5/webapps/chandler/-" {
   permission java.io.FilePermission "/etc/tomcat5.5/cosmo.properties", "read";
   permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
   permission java.lang.RuntimePermission "accessDeclaredMembers";
   permission java.lang.RuntimePermission "accessClassInPackage.org.apache.jasper.security";
   permission java.util.PropertyPermission "*", "read";
   permission java.lang.RuntimePermission "getProtectionDomain";
   permission java.net.SocketPermission "localhost:5432", "connect";
   permission java.io.FilePermission "/var/lib/tomcat5.5/temp", "read";
   permission java.io.FilePermission "/var/lib/tomcat5.5/temp/-", "read,write,delete";
   permission javax.management.MBeanServerPermission "findMBeanServer";
   permission javax.management.MBeanPermission "org.osaf.cosmo.*", "registerMBean";
   permission javax.management.MBeanTrustPermission "register";
};