Microsystems Technology Laboratories > OpenCoral
 

Install and Configure OpenCoral Prerequisites

This manual includes additional install notes for Coral prerequisite software on RHEL 5.0 and newer. It is likely that the lastest version of each of these packages will change frequently. As a result, I've listed most of the following commands with <version> in the command sequence. This should, of course, be replaced with the appropriate actual version number at the time of your installation.

Java

Coral servers run on the Java Standard Edition platform (known generally as J2SE). Note: Coral does not require or use the Java Enterprise Edition (known as J2EE). To download the appropriate package go to Java SE Downloads. Click on the link for JDK 6.0 Update <version> (As of 04/01/2010, that is JDK 6.0 Update 19.) Note, you don't want the update that includes either NetBeans or the update that includes Java EE. You do need the full JDK (Java Development Kit) but you do not need the JDK source code. For Linux, we recommend that you download and install the RPM version of the JDK. This will be downloaded and stored in the directory of your choosing as jdk-1_6_0_<version>-linux-i586-rpm.bin.

Note
Note: Coral servers must use JDK 6.0. as of Coral version coral-3_4_4. Coral versions of coral-3_4_3 may use either JDK 5.0 or JDK 6.0 (although versions coral-3_4_3 and older were originally released when JDK 5.0 was the standard supported version).
Note
Note: If you have a 64-bit machine, rather than simply choosing "Linux" as your platform, you should choose "Linux x64". Similar choices exist for Solaris SPARC, Solaris x86, and Solaris x64.

To install the JDK, become root by running the su command and entering the superuser password. Then change to the directory where this file was downloaded and issue the following commands:

# chmod a+x jdk-1_6_0_<version>-linux-i586-rpm.bin
# ./jdk-1_6_0_<version>-linux-i586-rpm.bin
# ln -s /usr/java/java-1.6.0_<version> /usr/j2se

The preceeding should install the java package in a standard location (/usr/java/jdk-1.6.0_<version>) and then create a link in /usr/j2se that points to that version. If you wish, you may remove the files jdk-1_6_0_<version>-linux-i586-rpm.bin and jdk-1_6_0_<version>-linux-i586.rpm when this step is complete.

Note
Many Linux distributions install, by default, the Gnu Linux Distribtution gcj. Furthermore, most distributions use a tool named alternatives to control which of several competing versions of java will become the default. To make sure that you will be using the Sun JDK, rather than gcj, make sure to complete the following steps ....

If your Linux distribution makes use of the alternatives system, you should make sure that the Sun JDK is the "preferred" Java by issuing the following commands:

# /usr/sbin/alternatives --install /usr/bin/java java /usr/j2se/bin/java 2
# /usr/sbin/alternatives --config java

When you issue the above '--config java' command, you should see that the default Java is still gcj and you will want to select /usr/j2se/bin/java (option 2) as the default.

When you are done, you should be able to make sure that you have the proper version of Java installed and accessible by issuing the command 'which java' followed by 'java -version'. If the version is not the Sun version of Java that you expect, you need to stop and figure out why. Trying to build Coral with the gcj version of Java will not work and will cause you additional effort to install.

Note
Coral also needs to be installed on any Linux or Solaris machines on which you expect to run local Coral clients. While those machines do not necessarily need to have the full JDK installed and can do quite nicely with the JRE (Java Runtime Environemt), you should be able to find java (which will be in /usr/j2se/bin/java) on all of these machines in the same location.

Ant

Ant is the Java build tool that is available from Apache. As if 11/01/2006, the latest version of Ant is 1.6.5, although version 1.7 has recently been released. Unless a more recent version has changes that are not backward compatible, the latest version can typically be downloaded and installed. Ant 1.<version> will be installed in /usr/local/ant. Download apache-ant-1.<version>-bin.tar.gz from Apache. Then, as root, issue the following commands:

# mv apache-ant-1.<version>-bin.tar.gz /usr/local
# cd /usr/local
# chmod 700 apache-ant-1.<version>-bin.tar.gz
# gunzip apache-ant-1.<version>-bin.tar.gz
# tar xvf apache-ant-1.<version>-bin.tar
# ln -s apache-ant-1.<version> ant

This will insure that /usr/local/ant/bin/ant always points to the latest version of ant, even if newer versions are installed.

HTTP Server

We will run the version of Apache HTTPD that comes with RHEL 4.0. As of this writing, that is version 2.0.52-28. In order to make sure that it starts when the server is restartd and that it is configured appropriately, we will issue the following commands: (as root)

# chkconfig --level 345 httpd on

Make sure that /etc/mime.types knows how to handle the JNLP files that will be used by Java Web Start. There should be a line that looks a lot like following line, that should have been added when the JDK was installed. Note: there may be variations in the syntax used in /etc/mime.types, but it should generally associate the type "application/x-java-jnlp-file" with an extension of "jnlp". Note: you will have to restart your Web server to have this change take effect.

application/x-java-jnlp-file     jnlp

PostgreSQL

We will use the PostgreSQL Database Server that comes with RHEL 5.4. As of this writing, that is 8.1.18-2. In order to make sure that it starts properly and ins configured properly, we will issue the following commands: (as root)

# chkconfig --level 345 postgresql on
Note
Some operating systems support a newer version of Postgres such as version 8.2 or newer. If this is the case, you will need to pay special attention to the setup of the database schema. In particular, Postgresql 8.0 and newer no longer support the internal column OID (for object ID, I think). As a result, on these newer databases, you will have to explicitly add the clause 'WITH OID' to insure that your tables are created with that option.

Now start the postgres database, which will initialize the /var/lib/pgsql/data location and place some default configuration files in that space. It will also help to insure that postgresql is installed correctly. To start the database issue the following command (as root): Note: normally, because of the above chkconfig command the database will start automatically any time the machine is rebooted so this is the only time that you should have to manually start the database server.

# /etc/init.d/postgresql start

The default postgres configuration is too liberal. Change /var/lib/pgsql/data/pg_hba.conf and change all methods of authentication to md5. We also need to make sure that we have appropriate md5 password authentication for the JDBC database connections that the Coral servers will use. Initially, the end of the pg_hba.conf file looks like:

local  all  all  ident  sameuser

A more reasonable set of connection rules for Postgres might look like the following where the original line has been commented out and replaced with several lines. These lines will force Postgres to use md5 authentication when connecting to the Coral database when either on a local host or when using a tcpip socket connection. In the following lines, you should replace CORAL_IP witht the IP address of the machine on which your Coral servers will run. Optionally, if you expect to run the Coral xReporter engine on a different machine, you should also uncomment the line that follows and then replace XREPORTER_IP with the IP addesss of that machine as well. Of course, if you haven't yet thought about xReporter, you can always make that change later.

#local  all  all  ident  sameuser
local  all  postgres  ident  sameuser
local  coral  all  md5
host coral all CORAL_IP  255.255.255.255 md5
#host coral all XREPORTER_IP 255.255.255.255 md5
Note
Make sure that you comment out the 'local all all ident sameuser' line in pg_hba.conf. Otherwise, it will assume that all database users (including the Coral database users) actually have a login account on this machine. The Coral database users are ONLY database users and DO NOT actually have login accounts on this machine.

Finally, Postgresql needs to be configured to allow TCP socket connections to the database. In Postgresql version 7.4, this is done by making sure that the following line appears in the file /var/lib/pgsql/data/postgresql.conf

tcpip_socket = true

If you are running a newer version of Postgresql such as version 8.1, the configuration that allows TCP socket connections is on by default, but you need to configure the 'listen_addresses' on this server which will accept socket connections. By default, there is a commented out line that looks like:

#listen_addresses = 'localhost'

This should be changed so that it listens on both 'localhost' as well as either the machine name or the IP address of your server. If this is a machine with multiple network interface cards (and, as a result, multiple IP addresses) you should use the one that is appropriate. Note: in the following, you can use either machine names or "dotted" IP addresses, as desired.

listen_addresses = 'localhost,your_server.your_institution.edu'
#listen_addresses = 'localhost'

Note: after editing pg_hba.conf and postgesql.conf you will normally have to restart Postgresql to have these changes take effect. This should be done by issuing the following commands as the root user:

# /etc/init.d/postgresql restart

Creating the coral user

We need to create a coral user and a group opencoral and to set up the appropriate environment variables for that user. To create the coral user issue the following commands: Note: in general, the coral user will "own" the coral source code and will own the coral server processes. In the following commands, we've assumed that the group opencoral will have a GID (group ID) of 1000 and that user coral will have a UID (user ID) of 40000, a home directory of /home/coral and a default shell of /bin/bash. If there is any conflict with other GID, UID, or you wish to assign a different home directory or a different shell, you are free to do so.

groupadd -g 1000 opencoral
useradd -c "Coral Software Owner" -d /home/coral -m -g 1000 -u 40000 -s /bin/bash coral
Note
You should also create the coral user and the opencoral group on other machines on which you expect coral will run as a local client or if you expect to use another machine's web server to distribute Remote Coral files. You will avoid problems if you insure the the UID (user ID, in this case of 40000) and GID (group ID, in this case 1000) match on all of those machines.
Note
In the following I have assumed that java is installed in /usr/j2se so that the java binary is found in /usr/j2se/bin/java. If java installed in a different location on you machine, you will need to adjust the definition of the JAVA_HOME environment variable accordingly.

To create the appropriate path and environment variables add JAVA_HOME and ANT_HOME to coral' environment. Add the following two lines to .cshrc in coral's home directory:

setenv JAVA_HOME /usr/j2se
setenv ANT_HOME /usr/local/ant
setenv PATH $JAVA_HOME/bin:$ANT_HOME/bin:$PATH

Alternatively, if you are using the bash shell, you can add the followning lines to .bash_profile in coral's home directory:

export JAVA_HOME=/usr/j2se
export ANT_HOME=/usr/local/ant
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
Note
You should also make these changes to the root users .cshrc or .bash_profile, as appropriate, because some of the build/deploy steps need to be performed as root and you want to make sure that both users find the correct version of both ant and, most importantly, java.

Compiling and installing Coral requires certain priviledged operations that are not normally given to "normal" users. Because it is often risky to do these things as root (AKA superuser) we make use of the "sudo" (superuser do) package to control who can perform certain special operations in a manner that is not as risky as always giving out and using the root password.

RHEL should come with the sudo package already installed. The configuation file for that package is normally located in /etc/sudoers. It is normally edited (as root) with the command visudo. Visudo is based on the vi editor. If you do not know how to use vi, we will also provide instructions as to how to add the appropriate lines to /etc/sudoers that does not require the use of vi. The set of lines that we want to add to the /etc/sudoers file are:

# User_Alias CORAL is the list of people who can manually start the
# opencoral system by running the script "opencoral".  This MUST
# include 'coral' (the owner of the Coral system) as well as any
# 'real' people authorized to start the opencoral system.
# Replace your_login and lab_manager with the login names of anyone you
# think should be allowed to start (or restart) the coral servers.
# Those people will, of course, need login accounts on the coral server.
User_Alias      CORAL = coral, your_login, lab_manager
 
# Host_Alias CORAL_SERVER should contain the machine name on which you
# expect to run the Coral servers.
Host_Alias      CORAL_SERVER = your_Coral_server_name_goes_here

# Runas_Alias CORAL_OWNER should ONLY include 'coral'
Runas_Alias     CORAL_OWNER = coral

# Cmnd alias specification
Cmnd_Alias      OPENCORAL = /usr/local/sbin/opencoral*
Cmnd_Alias      BUILD_CORAL = /usr/local/ant/bin/ant
Cmnd_Alias      SERVER_START = /bin/rm, /bin/kill, /bin/tee \
                                /usr/local/coral/sbin/server_s*
 
# Coral privilege specification
CORAL           CORAL_SERVER = NOPASSWD: BUILD_CORAL, OPENCORAL
CORAL           CORAL_SERVER = (CORAL_OWNER) NOPASSWD: SERVER_START
 
# Turn off the 'lecture' given before the first use of sudo because
# this will interfere with the automated build and run processes used
# in opencoral.
Defaults:CORAL          !lecture

Setting up your web server to distribute Remote Coral files

Remote Coral files and some of the configuration files need to be accessible from a web server. Configuration properties will allow you to specify that this is the web server that is running on the machine that is also the Coral server or, if you prefer, can be distributed by another web werver ... for examply, your main web site. In either case, you will need to set up a directory with appropriate permissions in which these files will be located.

Once you have decided which machine to use for this purpose, you need to determine the location of the httpd DocumentRoot on that machine. That is generally found in the httpd.conf file. On Linux machines, that is typically the file named /etc/httpd/conf/httpd.conf. In this case, you would find the DocumentRoot by issuing the command grep DocumentRoot /etc/httpd/conf/httpd.conf. On most Linux machines, the default DocumentRoot is /var/www/html. If this is the case, you should create an appropriate subdirectory under the DocumentRoot by issuing the commands as root:

mkdir /var/www/html/coral
chmod 775 /var/www/html/coral
chown coral:opencoral /var/www/html/coral
Note
You may have alternative values of both DocumentRoot and may also wish to locate the Coral files in a different location under DocumentRoot. You are welcome to change these locations appropriately but will need to remember to modify your Coral configuration parameters appropriately when you reach that stage.