H2O Installation

Version

H2O Release Version: 1.2.0

Overview

This document describes how to install the H2O system from the WAR file release. The WAR file release consists of a WAR file containing the web application and a set of scripts to create the database schema used by the application.

As of this writing, the installation has been tested on a Red Hat 7.3 system, running tomcat-4.1.18, JDK 1.4.1_01, and PostgreSQL 7.2.1. The system will probably work with versions of the listed software later than those above, but all other configurations are currently untested.

What you need to run H2O

A machine with: A machine (can be the same machine) with:

Installation Instructions

Web Application

For H2O to run correctly, you must modify a tomcat configuration file:

   ~/jakarta-tomcat-4.1.18/conf/web.xml
where ~/jakarta-tomcat-4.1.18 is your tomcat installation directory. You must set the enablePooling to false for the jsp servlet. The bold items below show what must be added to the web.xml file: 
    <servlet>
        <servlet-name>jsp</servlet-name>
        <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
        <init-param>
            <param-name>logVerbosityLevel</param-name>
            <param-value>WARNING</param-value>
        </init-param>
        <!-- start addition for H2O software -->
        <init-param>
            <param-name>enablePooling</param-name>
            <param-value>false</param-value>
        </init-param>
        <!-- finish addition for H2O software -->
        <load-on-startup>3</load-on-startup>
    </servlet>

Place the WAR file in the webapps directory of your tomcat installation (e.g. ~/jakarta-tomcat-4.1.18/webapps).

Start the tomcat server, and allow the application to auto-deploy. Some configuration will be necessary after deployment, so when tomcat has finished deploying the application, shut down the server. Before restarting tomcat, be sure that all configuration changes in this section have been made, and that the Database Initialization described below, is complete. When you restart tomcat, the home page for the application should be accessible from: 

    http://your.webserver.edu:<tomcat port>/h2o/index.jsp
General Configuration: h2o.properties
Open ~/webapps/h2o/WEB-INF/h2o.properties. Edit the "Per-Installation configuration" section to reflect your particular database, webserver, and mail settings. You may want to proceed with Database Initialization, described below, before editing the database settings.
Display Configuration: colors.jsp
The color scheme for the application is controlled via the ~/webapps/h2o/css/colors.jsp file. Changing these colors will modify the application style sheet. Because this file is a JSP, changes should take effect immediately.
Content Configuration
There are a few files that you will need to edit in order to customize the application for your purposes. All these files reside in ~/webapp/h2o/about. The application will present TODO messages until these files are edited. If you wish to modify the information About H2O, or the FAQ, you may edit the ~/webapp/h2o/about/about.jsp, and ~/webapp/h2o/about/faq.jsp files respectively.

Other content can be linked into the About H2O header, by adding your own files to the ~/webapp/h2o/about directory, then adding a links to each file in ~/webapp/h2o/header-about.jsp.

Database

Database Setup

In order to run the H2O database creation or update scripts, you must create a database user with the following privileges:

Both of these privileges must be set for the scripts to run correctly.

Database Creation
If you are updating H2O from a previous version, follow the instructions in the Upgrade Instructions section instead.

Scripts to build the database schema are included with this release. They can be found in the schema directory. To set up the database, first, set PGUSER, and PGPASSWORD in your shell environment to the database user and password. Make sure this user has create database and superuser privilege (see Database Setup). Next, from the distribution root directory, run the create-schema.sh script: 

     create-schema.sh -d [schema/create directory location] [db name]
     example: ./create-schema.sh ./schema/create h2o_db
to create the schema. Note that the above command will drop the database included on the commandline (after prompting first), so you should be sure to run it on a database you don't mind losing or on a database that doesn't exist yet.

Upgrade Instructions

The upgrade process is very straightforward. You basically just copy the new WAR file over the old one, copy a few working files over, update the database, and then restart. You want to make sure to back everything up in the process to make sure nothing gets lost, though. Specifically:

  1. Move h2o.war into a scratch directory and unjar it (jar xvzf h2o.war). Make sure not to unjar the file from within the tomcat/webapps directory, since doing so will overwrite the running version of system.
  2. Copy <scratch>/h2o/WEB-INF/h2o.properties.template to h2o.properties and edit to match tomcat/webapps/h2o/WEB-INF/h2o.properties. Note that the h2o.properties likely has had critical new properties added to it for the new release, so you can't just copy over the old version. I recommend doing a diff of the old and the new h2o.properties files to make sure that any differences are intended.
  3. Shutdown tomcat. Obviously, starting with this step and ending with the starting tomcat step, the server will be down, so it's a good idea to have a good grasp of what you'll be doing in between before shutting down the server!
  4. Make a backup copy of your entire tomcat/webapps/h2o directory to a safe spot.
  5. Make a dump of your current h2o database to file. On our system, we run 'pg_dump h2o > h2o_upgrade_<date>.dump'.
  7. Take a breath and confirm that you really just made those backups.
  8. Copy index/ and uploads/ directories from tomcat/webapps/h2o/WEB-INF to <scratch>/h2o/WEB-INF. Make sure that you preserve permissions through the copy (I recommend using 'cp -av ...' in unix).
  9. Perform a database update as described below.
  10. Move tomcat/webapps/h2o to a backup location. Move the new <scratch>/h2o directory into tomcat/webapps.
  11. Start the tomcat server and verify that h2o is running.

    12. Database Update

    If you are updating H2O from a previous version, you must run database update scripts against your existing H2O database schema.

    It is advised you backup your data with a database dump before trying any upgrade.

    Scripts to update the database schema are included with this release. They can be found in the schema directory. Make sure your shell environment (PGUSER, PGPASSWORD) is set to your existing h2o user. Make sure this user has create database and superuser privilege (see Database Setup). Next, from the distribution root directory, run the run-sql-scripts.sh script: 

         run-sql-scripts.sh [schema/update/ver directory location] [db name]
     example: ./run-sql-scripts.sh ./schema/update/1.0 your_h2o_db
    to update the schema. You need to run this command once for each version in between the one you are running and the one you are upgrading to, including the one you are upgrading to. For instance, if you are upgrading from 1.0 to 1.2.0, you will need to run the above command for the following versions in the following order: 1.1.1, 1.1.3, 1.2.0 (skipping 1.1.2 because no such schema/update/ directory exists). After these scripts complete, the database should be compatible with the current version of the code.

    System Maintenance

    Setting Site Administrators

    To make a use a site administrator or take administrator rights away from an existing administrator, use the included set-administrator.sh script. A site administrator has the ability to login to the site as any user via a 'Login As' button on each user profile page.