Installation

To deploy an ICAT you need:

  1. a suitable container to support EJBs,
  2. databases on a system supported by eclipselink,
  3. to configure glassfish,
  4. to install a copy of icat.properties and log4j.properties in the correct place,
  5. deploy the .ear file,
  6. and see if it works.

EJB Container

In principle you can use any EJB container. Testing has been performed with glassfish 3.1 and these notes refer to that version.

You must already have a Java SE installed (i.e. the command "java" is known), then you can get Java EE 6 SDK Update 4 with JDK 6 Update 31 or later from http://www.oracle.com/technetwork/java/javaee/downloads/index.html and execute the script.

Request custom installation, install and configure, and enter proxy details if necessary on your site. Request a server domain, set the domain name and set the admin password. For a secure deployment of glassfish you should obtain a trusted certificate rather than using the self-signed one in the distribution.

Databases

The database system must be supported by eclipselink. This includes most database systems you are likely to want as explained at the eclipselink web site. It has been tested with: MySQL, Oracle and Derby. You will need two empty schemas/databases both with permissions for data definition operations such as "CREATE TABLE ..." You must place a copy of the "JDBC Connector" for your database in the lib directory below the domain where you will install icat. You should get the connector from the database supplier. In the case of Oracle this is ojdbc14.jar or ojdbc16.jar and for MySQL it is something like mysql-connector-java*.jar. MySQL must be installed with InnoDB support. Eclipselink, which is used by ICAT, will ensure that MySQL tables make use of the InnoDB engine. In the case of Derby the connector comes pre-installed with Glassfish however we do not expect Derby to be used for production work.

Preparing glassfish.props

Obtain icat.ear-4.1.1-config.zip and unzip it. You must first edit glassfish.props to match your system.

driver
is the name of the jdbc driver and must match the jar file for your database that you stored in the previous step.
icatProperties
identifies the main icat database and how to connect to it.
icatuserProperties
identifies the authentication database and how to connect to it
glassfish
is the top level of the glassfish installation. It must contain "glassfish/domains", and will be referred to here as GLASSFISH_HOME as if an environment variable had been set.
port
is the administration port of the chosen glassfish domain which is typically 4848.

For a local oracle-xe installation the following values of driver, icatProperties and icatuserProperties should be good except for the user and password values:

driver=oracle.jdbc.pool.OracleDataSource
icatProperties=url="'"jdbc:oracle:thin:@//localhost:1521/XE"'":ImplicitCachingEnabled=true:MaxStatements=200:user=icat:password=secret
icatuserProperties=url="'"jdbc:oracle:thin:@//localhost:1521/XE"'":ImplicitCachingEnabled=true:MaxStatements=200:user=icatuser:password=anotherSecret

Note the "'" which is needed because the url contains colons which also separate individual properties.

For MySQL:

driver=com.mysql.jdbc.jdbc2.optional.MysqlDataSource
icatProperties=user=icat:password=secret:databaseName=icat
icatuserProperties=user=icat:password=anotherSecret:databaseName=icatuser

Using glassfish.props to configure Glassfish

Having prepared the glassfish.props file you should run the command: asadmin login to login as admin. This will prompt you for your glassfish admin password to avoid being prompted for it later. If you do not do this the next step will fail. You will find the asadmin executable in the bin directory below the directory you have identified in glassfish.props as "glassfish" - i.e. $GLASSFISH_HOME/bin/asadmin. There is no logout command but you can delete ~/.asadminpass if you wish once you have run the create.sh script successfully. Now check that your domain is running with asadmin list-domains and try running create.sh . It expects to find glassfish.props in the current directory. Amongst other things the script will try to "ping" the database. If you have problems, modify the glassfish.props, run drop.sh and then create.sh again.

icat.properties and log4j.properties

In the unpacked icat.ear-4.1.1-config.zip file you will find two properties files which should both be copied to the config directory for your chosen glassfish domain. You will find your domain directory at $GLASSFISH_HOME/glassfish/domains. The log4j.properties file should not need modification initially. It will result in an icat.log file being written to the logs directory below your domain. The icat.properties file will probably need changing:

auth.classname
is the class name of the chosen authentication plugin. org.icatproject.useransto.facility.AnstoUser gives you just an authentication table (USER_TABLE_ANSTO in the icatuser database) while org.icatproject.userldap.facility.LdapUser provides an LDAP authentication mechanism in addition to the authentication table (USER_TABLE in the icatuser database).
auth.ldap.provider_url
is the url of the ldap authenticator and is only required if you have selected ldap authentication.
auth.ldap.security_principal
is also only required for ldap authentication. The % character in the security_principal will be replaced by the specified user name. If you just use % then the user must enter a complete security_principal as the user name.
auth.ldap.ip
if set applies only to the ldap authentication and restricts the IP addresses from which a user may authenticate. The value is a space separated list of IPV4 or IPV6 addresses followed by the number of bits (starting from the most significant) to consider. For example 172.16.68.0/24 allows access from 172.16.68.0 to 172.16.68.255.
auth.ansto.ip
behaves as auth.ldap.ip if the "Ansto" (database table only) authentication has been selected.

Installing the .ear file

If you already have an icat installed then you should first remove it with asadmin --port 4848 undeploy <ear> where the value of "ear" can be found by: asadmin --port 4848 list-applications Obtain icat.ear-4.1.1.ear and install it with the command: asadmin --port 4848 deploy icat.ear-4.1.1.ear . If you have only one domain you may not need to specify the port and if the admin port is not 4848 then specify the correct value.

As the file is deployed the databases are created. Login in to the icatuser database and add one line to the USER_TABLE (for ldap authentication) or otherwise to the USER_TABLE_ANSTO. The user_id must be "root" in lower case and the password is one of your choosing. You can add other users here if you wish. If you are using ldap authentication you will probably only want "root" to be entered this way.

Check that ICAT works

There is one more file in the unpacked icat.ear-4.1.1-config.zip file: test.py . This is a python script which requires that the suds client is available. On CENTOS this is packaged as a python-suds RPM. Invoke the script with two parameters: the hostname and port separated by a colon on which the service is deployed securely (typically localhost:8181) and the root ICAT password you stored in the database. It should report:

Login, search, create, delete and logout operations were all successful.

This script can be run at any time as it is almost harmless - it simply creates a "Group" with an unlikely name and removes it again.

In case of problems look at the log files: server.log and icat.log which can both be found in the logs directory below your domain.