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 and minimally with Tomcat 6.0.16
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.
- Download and unpack
osaf-server-bundle-x.y.z
- Create a database (see CosmoDatabaseSetup).
- Install (or make sure you already have) the API dependencies (see CosmoServletContainerRequirements)
- Check that your Logging is setup to use log4j.
- 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)
- Setup the context (see Context configuration below).
- Set
$JAVA_OPTS
in the Tomcat user's environment (see CosmoStartupConfiguration) . (TODO this will be unneeded from releases later than 0.12.0)
- Set the security permissions (see Security below).
- Copy
cosmo-x.y.z.war
into Tomcat's application base directory, renaming it to chandler.war
($CATALINA_HOME/webapps
by default).
- 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)
- Restart Tomcat.
Tomcat 6 specific instructions
- Ensure the following jars are added to
$CATALINA_HOME/lib
folder
- derby-[ver].jar (if using Derby)
- mysql-connector-java-5.0.4.jar (if using MySQL?)
- postgresql-8.3-604.jdbc4.jar (if using PostgreSQL?)
- mail-1.4.jar
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 "%r" %s %b "%{Referer}i" "%{User-Agent}i""
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
Cosmo uses the deprecated Commons-Logging. To use the logging backend of your choice, install the following files to your $CATALINA_HOME/lib from the SLF4J project, release 1.5.6 (or newer)
-
jcl-over-slf4j-1.5.6.jar
-
log4j-over-slf4j-1.5.6.jar
-
slf4j-api-1.5.6.jar
and then one of the
slf4j-X-1.5.6.jar
files. To pipe all logging to the Java Logger (recommended), add the file
slf4j-jdk14-1.5.6.jar
Security
Depending on how strict your security policy is, you may need to allow the following permissions in your policy scripts ("webcal" and "cosmo.properties" paths may need editing for your site)
grant codeBase "file:${catalina.home}/webapps/webcal/-" {
permission java.io.FilePermission "${catalina.home}/webapps/webcal/-", "read";
permission java.io.FilePermission "${catalina.home}/etc/cosmo.properties", "read";
permission java.io.FilePermisison "${catalina.home}/lib/-", "read";
permission java.io.FilePermission "${java.home}/lib/xerces.properties", "read";
permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.RuntimePermission "createClassLoader";
permission java.lang.RuntimePermission "getProtectionDomain";
permission java.lang.RuntimePermission "getClassLoader";
// this is for PostgreSQL. Change the port number for other DBs
permission java.net.SocketPermission "localhost:5432", "connect";
permission javax.management.MBeanServerPermission "findMBeanServer";
permission javax.management.MBeanPermission "org.osaf.cosmo.*", "registerMBean";
permission javax.management.MBeanPermission "org.osaf.cosmo.*", "unregisterMBean";
permission javax.management.MBeanTrustPermission "register";
permission javax.security.auth.AuthPermission "modifyPrincipals";
// these ones are a bit dodgy
permission java.lang.RuntimePermission "accessClassInPackage.*";
permission java.util.PropertyPermission "*", "read";
permission java.io.FilePermisison "${catalina.home}/logs/-", "read";
permission java.io.FilePermission "${catalina.home}/temp", "read";
permission java.io.FilePermission "${catalina.home}/temp/-", "read,write,delete";
};