Chandler Wiki : Cosmo Tomcat

Product | Planning | Teams | Developers | Notes
r10 - 22 Jan 2009 - 09:38:18 - SamHallidayYou are here: OSAF > Documentation Web > CosmoAdministrator > CosmoTomcat
%ICON_COSMO_LOGO%
---+ !!Deploying Cosmo in Tomcat
---
%TOC%
---

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=
   1 Create a database (see CosmoDatabaseSetup).
   1 Install (or make sure you already have) the API dependencies (see Documentation.CosmoServletContainerRequirements)
   1 Check that your <a href="#Logging">Logging</a> is setup to use log4j.
   1 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)
   1 Setup the context (see <a href="#Context%20configuration">Context configuration</a> below).
   1 Set =$JAVA_OPTS= in the Tomcat user's environment (see CosmoStartupConfiguration) . (*TODO* this will be unneeded from releases later than 0.12.0)
   1 Set the security permissions (see <a href="#Security">Security</a> below).
   1 Copy =cosmo-x.y.z.war= into Tomcat's application base directory, renaming it to =chandler.war= (=$CATALINA_HOME/webapps= by default).
   1 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)
   1 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 =&lt;Engine&gt;= configured in =server.xml=, ={host}= is the name of the =&lt;Host&gt;= 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

<div class="box">
<verbatim>
<?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>
</verbatim>
</div>

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)

<div class="box">
<verbatim>
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";
};
</verbatim>
</div>
chandlerproject.org
VISION
TOUR
Download Desktop
Get a Hub Account
Get Chandler Server
FAQ
Get Started
Blog
Mailing Lists
Chat on IRC
Report a Bug
Get Involved
OSAF Community
About OSAF
Documentation Wiki Changes
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.