Install and Configure OpenCoral Prerequisites
This manual includes additional install notes for Coral prerequisites on RedHat/Centos. 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). You do need the full JDK (Java Development Kit) but you do not need the JDK source code. For Linux, we recommend that you use the JDK8 that comes as part of your operating system.
Ant
Ant is the Java build tool that is available from Apache. Most Linux-based operating systems have this available as part of a typical installation. Unless a more recent version has changes that are not backward compatible, the latest version can also 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 our operating system. 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 our operating system. In order to make sure that it starts properly and is configured properly, we will issue the following commands: (as root)
# chkconfig --level 345 postgresql on
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 or scram256. We also need to make sure that we have appropriate 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
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 Newer versions may have a slightly different option.
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
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
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