Cosmo 0.2 Installation

Bundled Distribution

To install and run the Tomcat-bundled distribution of Cosmo, perform the following steps:

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 release from http://java.sun.com/j2se/1.5.0/download.jsp (look for "Download JRE 5.0 Update ")
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.

Download Cosmo

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 cosmo-0.x.x). For the purposes of these instructions, the symbolic name $COSMO_HOME is used to refer to the full pathname of the release directory.

NOTE: As an alternative to downloading a binary distribution, you can create your own from the source repository, as described at CosmoZeroPointTwoBuildInstructions.

Configure Cosmo (OPTIONAL)

Perform advanced configuration for host security, logging, SSL, reverse proxy support etc. Discussion on these topics is found elsewhere in the manual.

NOTE: The default configuration is sufficient for casual users.

Run Cosmo

Cosmo can be started by executing the following command:

Unix

$COSMO_HOME/bin/cosmoctl start

Windows

-- not yet supported --

NOTE: On Solaris you will need to alter $COSMO_HOME/bin/cosmoctl to invoke /bin/bash - Change the first line to: #!/bin/bash

Cosmo will likely require more memory than the default allocated to it by the operating system, so you may wish to pass command line options to the JVM to increase the available memory:

Unix

JAVA_OPTS='-Xms256m -Xmx256m' $COSMO_HOME/bin/cosmoctl start

Windows

-- not yet supported --

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

Check $COSMO_HOME/logs/cosmo.log for messages like the following:

2005-09-15 15:16:53,568 INFO  [Catalina] Initialization processed in 885 ms
2005-09-15 15:16:55,376 INFO  [LifecycleLoggerListener] Cosmo webapp starting
2005-09-15 15:17:05,027 INFO  [Catalina] Server startup in 11457 ms

See CosmoLogging for more information on Cosmo's log output.

Use Cosmo

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

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

You can log into cosmo as the root user (password cosmo). Immediately change the root user's password in the "Users" section of the admin console.

You can use a WebDAV client to view user home directories at:

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

Webapp Distribution

Future releases of Cosmo will provide a standalone webapp distribution that you can deploy into an existing application server. Advanced users should be able to do this today by examining the customized config files in the Tomcat bundled distribution.

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 $COSMO_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 CosmoAdministratorFaq for answers to common installation questions. If you cannot find a solution to your problem, send your question to cosmo@osafoundation.org.