r10 - 22 Jan 2009 - 09:38:18 - SamHallidayYou are here: OSAF >  Documentation Web  >  CosmoAdministrator > CosmoTomcat
Cosmo web server

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.

  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 will be unneeded from releases later than 0.12.0)
  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.

Tomcat 6 specific instructions

  1. 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 &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

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";
};
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r10 < r9 < r8 < r7 < r6 | More topic actions
 
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.