Prerequisites

Grid-SAFE, is a Java application which normally runs in Tomcat and uses a MySQL database to store data. There is also a command line tool that allows most operations to be performed without Tomcat running, though this still requires MySQL.

MySQL

Grid-SAFE requires a MySQL database which can be downloaded from the MySQL website, we recommend using mysql-5.0 or above.

Set up the database

A database, <gridsafe-database>, needs to be created.

        mysql> create database <gridsafe-database>;

e.g.

        mysql> create database gridsafe;

A user should be created with read and write access to the database.

        mysql> GRANT ALL PRIVILEGES ON <gridsafe-database>.* TO '<gridsafe-username>'@'localhost' IDENTIFIED BY '<gridsafe-password>';
        Query OK, 0 rows affected (0.00 sec)

e.g.

        mysql> GRANT ALL PRIVILEGES ON gridsafe.* TO 'gridsafe'@'localhost' IDENTIFIED BY 'gridsafe';
        Query OK, 0 rows affected (0.00 sec)

It is not necessary to create any tables in the database as Grid-SAFE will automatically create any required tables as needed.

Java

Grid-SAFE uses some features of Java 5, so it or a higher version must be downloaded and installed from the Java website. You need to install a JDK version of Java as this is required by tomcat.

The remaining pre-requisits only apply to the web-portal not to the command-line tools.

Tomcat

Apache Tomcat is also required for the web-portal. Tomcat can be downloaded from the Tomcat website. This site also provides documentation for setting up and installing tomcat. We develop against recent versions of tomcat 5.5, though the software should also work with tomcat 6.

Apache Web server

The web-portal expects authentication to be handled by the tomcat container or by a separate web-server (such as apache) acting as a front-end to tomcat. Tomcat supports a number of different authentication mechanisms and if these meet your requirements then you can run tomcat as a stand-alone application container. A much wider selection of authentication mechanisms are available if you use a web-server front-end. Use whatever mechanism best suites your needs, but it will be easier to configure the reports if the username somebody uses to authenticate with the web-server/tomcat matches their username on the HPC service.

To use apache as a front-end to tomcat you need to install an AJP connector module into the web server. The ajp_proxy that comes as part of the apache-2.2 distribution is suitable for this. When building from souce make sure you specify the --enable-proxy --enable-proxy-ajp flags to configure to make sure this module is built.

In the apache configuration restrict access to the application URL using a Location statement.

<Location /gridsafe>
AuthType Basic
AuthName "Grid-SAFE login"
AuthUserFile /etc/apache/conf/password
AuthGroupFile /etc/apache/conf/group
Require valid-user
</Location>

Note that if you wish to upload new accounting data through http rather than using the command line tools then this will be posted to the UploadServlet? URL so you may wish to configure additional constraints on this URL.

You then need to tell apache to pass on all requests below this URL to tomcat.

<Location /gridsafe/>
   ProxyPass ajp://localhost:8009/gridsafe/
</Location>

Set up the Tomcat

For a production server it is important to run Tomcat daemon in headless mode. To do this run

        export CATALINA_OPTS="-Djava.awt.headless=true"

on the command line or in the Tomcat startup script.

Tomcat Authentication configuration

By default Tomcat ignores any authentication information passed from apache. If you wish to use apache to perform authentication you need to edit the AJP connector entry in the server.xml file (in tomcats configuration directory) to use the username as generated by the web-server.

   <Connector port="8009" tomcatAuthentication="false"
               enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

If your preferred authentication mechanism is available directly in tomcat you can omit the apache webserver entirely. However this means you will need to unpack the war file in order to modify the web.xml to define security constraints for the application. e.g.

<security-constraint>
    <web-resource-collection>
      <web-resource-name>Upload servlet </web-resource-name>
			<url-pattern>/UploadServlet/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
			<role-name>upload</role-name>
    </auth-constraint>
  </security-constraint>
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Application </web-resource-name>
			<url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
			<role-name>*</role-name>
    </auth-constraint>
  </security-constraint>
  <!-- Define the Login Configuration for this Application -->
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>WEBAPP</realm-name>
  </login-config>
<security-role><description>Data upload role</description><role-name>upload</role-name></security-role>
<security-role><description>Any user of the system</description><role-name>user</role-name></security-role>

Unfortunately it is not possible to have a single web.xml file that works with both apache and tomcat authentication or to override these settings at the container level.

Database configuration

Next the database connection needs to be configured so that gridsafe can connect to the database. This requires a number of Configuration Properties to be set e.g.

db_driver=com.mysql.jdbc.Driver
db_username=demo
db_password=demo
db_name=jdbc:mysql://localhost/demo

There are several places you can set these:

On the java command line
In the deploy-config.properties file inside the application jar/war file
in the warfile configuration XML file

If you are using the tomcat XML configuration file you also have the option to configure a Database Connection Pool (DBCP) (see the tomcat documentations). For example add a gridsafe.xml containing a description of the resource to the /opt/apache-tomcat-5.5.27/conf/Catalina/localhost directory and add the jdbc driver (mysql-connector-java-5.1.6-bin) in the in /opt/apache-tomcat-5.5.27/common/lib directory (NOTE: This file, which we have name gridsafe.xml must be the same name as the service you are running, i.e. the same name as the war file or the directory in ${catalina.home}/webapps/ that the service is deployed in).

        <?xml version="1.0" encoding="UTF-8"?>
        <Context 
             privileged="true" 
             antiResourceLocking="false" 
             antiJARLocking="false">    
                     <Resource 
                        name="jdbc/gridsafeDB" 
                        auth="Container"
                        type="javax.sql.DataSource" 
                        removeAbandoned="true"
                        removeAbandonedTimeout="30" 
                        maxActive="100"
                        maxIdle="30" 
                        maxWait="10000" 
                        username="<your-username>"
                        password="<your-password>"
                        driverClassName="com.mysql.jdbc.Driver"
                        url="jdbc:mysql://localhost/gridsafe"/>  
                   <Parameter name="connection.pool" value="jdbc/gridsafeDB"  override="true" />

             </Context>

You can also override gridsafe configuration properties in this xml file. In the above example we are changing the name of the connection pool but other parameters can also be overridden in this way.