OSAF Server Bundle Installation

---

---

Existing Tomcat and other J2EE Application Servers

For information on getting cosmo to run on an existing Tomcat or other J2EE application server see:

• CosmoTomcat
• CosmoJBoss
• CosmoGlassFish
• CosmoWeblogicTen

Prerequisites

Java Runtime

If your operating system does not already provide it (try running java -version and/or echoing $JAVA_HOME), download and install a Java Runtime Environment (version 5.0, sometimes called 1.5):

1. Download a JRE (Sun's is available at http://java.sun.com/j2se/1.5.0/download.jsp - look for "Download JRE 5.0 Update <x>"). (you need to download the JRK - the SDK version in fact)
2. Install the JRE according to the instructions included with the release.
3. Set an environment variable JAVA_HOME to the pathname of the directory into which you installed the JRE (the root directory not the bin directory).

Installation

Download the server bundle

1. Download a binary distribution from http://downloads.osafoundation.org/cosmo/releases/
2. Unpack the binary distribution into a convenient location so that the distribution resides in its own directory (conventionally named osaf-server-bundle-x.x). For the purposes of these instructions, the symbolic name $OSAFSRV_HOME is used to refer to the full pathname of the release directory.

As an alternative to downloading a binary distribution, you can create your own from the source repository. See ServerBundleBuildInstructions for instructions on how to do this. Once you have built the distribution, return to these instructions to get it up and running.

Upgrading from previous versions

The server bundle includes a migration component under $OSAFSRV_HOME/migration . See the README in that directory for more information. Upgrading may be as simple as pointing the new install to the previous database if there are no schema changes (for example upgrading from 0.7.0 to 0.7.1). If you are using the embedded derby database (default configuration) this can be accomplished by:

1. rename $OSAFSRV_HOME/db to $OSAFSRV_HOME/db_old
2. copy old $OSAFSRV_HOME/db to new $OSAFSRV_HOME/db
3. run the new server

On startup, the server verifies that the database contains the correct schema version. The server will not start unless the schema version is up to date.

For information on the migration component see:

• CosmoMigrationDevelopers
• CosmoMigrationUsers

Optional configuration

The default configuration is sufficient for most users. If you have advanced requirements for host security, logging, SSL, reverse proxy support etc, see the discussion on these topics elsewhere in the manual.

Run the server

The server can be started by executing the following command:

Unix

$OSAFSRV_HOME/bin/osafsrvctl start

Windows

$OSAFSRV_HOME\bin\osafsrvctl.bat start

(You may need to alter $OSAFSRV_HOME/bin/osafsrvctl to invoke bash by changing the first line to #!/bin/bash or wherever your system's shell interpreter is located.)

Initial database population

The first time you start the server, Cosmo will populate its database with tables and seed data. This will cause the first startup to take several seconds. Subsequent startups will be much faster. Note that Cosmo will fail to start if it cannot connect to the database configured in $OSAFSRV_HOME/tomcat/conf/Catalina/localhost/chandler.xml.

Tuning the server

The server will likely require more memory than the default allocated to it by the operating system, so if you are going to have many users with large collections, you may wish to give the JVM more memory. You can do this by setting the $JAVA_OPTS environment variable before starting the server:

Unix

JAVA_OPTS='-Xms512m -Xmx512m' $OSAFSRV_HOME/bin/osafsrvctl start

Windows

JAVA_OPTS='-Xms512m -Xmx512m' $OSAFSRV_HOME\bin\osafsrvctl.bat start

See ServerBundleStartupConfiguration for more tuning information.

Running in the foreground

If you want Tomcat to run in the foreground rather than daemonizing, execute osafsrvctl run instead.

Verify the startup

Check $OSAFSRV_HOME/logs/osafsrv.log for messages like the following:

2007-07-11 12:43:01,325 INFO  [Catalina] Initialization processed in 733 ms
2007-07-11 12:43:05,256 INFO  [LifecycleLoggerListener] Chandler Server 0.7.0-SNAPSHOT starting
2007-07-11 12:43:06,728 INFO  [CosmoPropertyPlaceholderConfigurer] Loading properties file from URL [file:etc/cosmo.properties]
2007-07-11 12:50:37,062 INFO  [DbInitializer] Creating database
2007-07-11 12:50:38,070 INFO  [DbInitializer] Initializing database
2007-07-11 12:50:38,070 DEBUG [DbInitializer] adding overlord
2007-07-11 12:50:38,072 DEBUG [StandardUserService] creating user root
2007-07-11 12:43:13,660 DEBUG [StandardUserService] getting user root
2007-07-11 12:43:14,859 INFO  [Catalina] Server startup in 10681 ms

See ServerBundleLogging for more information on the bundled server's log output.

Use the server

After startup, the server's welcome page is viewable at:

• http://localhost:8080/
• https://localhost:8443/ (if you enabled SSL)

This page describes how to log into Cosmo. Immediately log in (username of "root" and default password of "cosmo") and change the root user's password in the "Users" section of the admin console.

Troubleshooting

Port Conflict

By far the most common problem is having another process already listening on port 8080. If this is the case, you will need to change the port on which Tomcat's connector listens. Edit the Connector entry in $OSAFSRV_HOME/tomcat/conf/server.xml and change the port attribute to specify a port that isn't in use (and that the user running the Tomcat has the privilege to use):

<Connector port="8080" enableLookups="false"/>

If the existing process is running another instance of Tomcat, you may also need to change this instance's shutdown port:

<Server port="8005" shutdown="SHUTDOWN">

FAQ

See FAQ for answers to common installation questions. If you cannot find a solution to your problem, send your question to cosmo@osafoundation.org (see CosmoHome for subscription instructions).