Server Bundle Startup Configuration

The server bundle provides a wrapper script for Tomcat's startup script that uses environment variables to configure some Cosmo features as well as the JVM itself.

Wrapper Script Configuration

$OSAFSRV_HOME/bin/osafsrvctl is a wrapper script for $OSAFSRV_HOME/tomcat/bin/catalina.sh that examines environment variables to determine values for certain system properties before starting Tomcat.

The environment variables recognized by osafsrvctl are:

$OSAFSRV_DERBY_ERROR_LOG

Sets the location for derby.stream.error.file. $OSAFSRV_HOME/logs/derby.log by default. Value is used without modification to set the system property.

$OSAFSRV_DERBY_ERROR_LOG_APPEND

Sets the value of derby.infolog.append. True by default, set to 0 or false to change.

These environment variables can be specified in the user environment or in $OSAFSRV_HOME/bin/osafsrvcfg.

For more information on the system properties used by Cosmo, see CosmoStartupConfiguration. For those system properties required by other bundled components, see below.

JVM Configuration

The JVM itself often needs to be tuned for performance, memory usage, garbage collection, etc. Advanced JVM tuning is beyond the scope of this document, but here are some useful tips and observations.

Configuration options are passed to the JVM via the $JAVA_OPTS environment variable. osafsrvctl automatically includes -server to use the server VM.

All JVMs

Large Cosmo calendars are extremely memory intensive. You will want to bump the amount of heap available to the server. It is a generally accepted best practice to set the minimum and maximum heap sizes equal to each other. You will also probably want to increase the size of the "permanent generation", which stores information about the objects in the heap.

    JAVA_OPTS="$JAVA_OPTS -XX:PermSize=128m -XX:MaxPermSize=256m -Xms512m -Xmx512m"

The nonstandard options (those beginning with -XX) are not guaranteed to work on all JVMs. They do however work on the ones listed below.

Sun

There are no known issues with the Sun JVM with Cosmo 0.15.

Docs for the Sun HotSpot JVM are at http://java.sun.com/docs/hotspot/VMOptions.html.

Bea Jrockit

OSAF internal testing has found Jrockit to be more stable and performant than the Sun JVM. Your mileage may vary. Only testing in your environment will tell you for sure.

Find Jrockit's docs at http://edocs.bea.com/jrockit/webdocs/index.html.

Database Configuration

As of version 0.5, Cosmo stores its data in a relational database (either embedded or remote). The server bundle comes configured to use the embedded Derby database, but also supports running against a MySQL 5 database server. Other databases (such as Postgres) may be used, but they haven't been tested as much. Please share any experiences with other databases.

Derby

Certain features of Derby are configured via system properties passed as command line options to the JVM. The osafsrvctl script sets these command line options based on environment variables (see above).

derby.stream.error.file=</path/to/derby/log/file>

directs Derby's logging output to a file (Derby does not use log4j or commmons-logging like the rest of the Cosmo components so it has to be configured specially here). Paths are relative to the directory in which the JVM was started. Default: derby.log

derby.infolog.append=[true|false]

controls whether Derby will append to an existing log at startup or overwrite it. Default: false

MySQL 5

To configure Cosmo to run against a MySQL 5 database:

1. Create a new database ("cosmo" for instance) on a MySQL 5 server. Make sure the default charset is utf8, and the default table engine is InnoDB.
   • mysql -uroot -e"create database cosmo character set utf8"
2. Edit $OSAFSRV_HOME/etc/cosmo.properties and change the property cosmo.hibernate.dialect to org.osaf.cosmo.hibernate.CosmoMySQL5InnoDBDialect.
3. Edit $OSAFSRV_HOME/tomcat/conf/Catalina/localhost/chandler.xml
   • Comment out the <Resource> definition for the Derby datasource, and uncomment the example <Resource> definition for a MySQL datasource
   • Set the datasource properties to match your MySQL database server by editing the url entry and change [server] to your server name (most likely localhost) and change [db] to the name of the MySQL database you created for Cosmo.
   • Make sure your username and password entries match the MySQL user information
4. Start Cosmo and the database schema will automatically be created the first time.

PostreSQL 8

To configure Cosmo to run against a PostreSQL 8 database:

1. Create a new database ("cosmo" for instance) on a Postgres server. Make sure the default charset is utf8.
2. Edit $OSAFSRV_HOME/etc/cosmo.properties and change the property cosmo.hibernate.dialect to org.osaf.cosmo.hibernate.PostgreSQLDialect.
3. Edit $OSAFSRV_HOME/tomcat/conf/Catalina/localhost/chandler.xml
   • Comment out the <Resource> definition for the Derby datasource, and uncomment the example <Resource> definition for a Postgres datasource
   • Set the datasource properties to match your Postgres database server by editing the url entry and change [server] to your server name (most likely localhost) and change [db] to the name of the Postgres database you created for Cosmo.
   • Make sure your username and password entries match the Postgres user information
4. Start Cosmo and the database schema will automatically be created the first time.