EJB Container

In principle you can use any EJB container. Testing has been performed with glassfish 3.1.2 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 schema is almost identical to that used for ICAT 4.1 (the only difference is that some text columns are wider) and is identical to that used for ICAT 4.2.0. So if you already have a 4.1 or 4.2 database installed there is no need to start with an empty schema, and you can skip this section.

The database system must be supported by eclipselink and must support transactions and enforce foreign key constraints. 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 an empty schema/database 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 and you must ensure that while installing ICAT the default engine is InnoDB. You can see the default engine with "show engines;". To fix an existing system you can use the ALTER TABLE command as explained in: storage-engine-setting

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.2.5-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 icat 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 should be good except for the user and password values:

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

For MySQL:

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.

Install and configure authentication plugins

You should obtain appropriate authentication plugins - such as authn_db or authn_ldap or you may wish to build your own following the instructions for Authentication plugins . Each plugin has its own configuration mechanism. Make sure that all plugins are listed in the icat.properties file which is described in the next section. If you install or modify a plugin after the icat ear file then you will need to reload the icat application.

icat.properties and log4j.properties

In the unpacked icat.ear-4.2.5-config.zip file you will find an icat.properties properties files which should be copied to the config directory for your chosen glassfish domain. You will find your domain directory at $GLASSFISH_HOME/glassfish/domains. There is also a file called log4j.properties.example to configure the icat logging. A copy of this file already exists in the .ear file so unless you wish to modify the logging configuration this file is not needed. If you do wish to modify logging, then place a copy of the file somewhere with a name of your choice (icat.log4j.properties might be a good name) and update the icat.properties file to reference it as explained below. The icat.properties file may need other changes:

lifetimeMinutes

Defines the lifetime of an ICAT sessionid. You should avoid making it have a long duration as this increases the risk if it is intercepted, lost or stolen.

rootUserNames

Is a space separated list of user identifiers having full access to the authorization tables: Rule, Group, User and UserGroup. The format of the user identifier is determined by the chosen authentication plugin. The authn_db and authn_ldap plugins may be configured to either return the simple user name or to prepend it with a name identifying the mechanism. For example if there is a an entry "root" in the database then if the authn_db authenticator is configured without a mechanism then the user name to consider will be just "root", however if it has been configured with a mechanism of "db" then the string "db/root" must be specified.

authn.list

is a space separated set of mnemonics for user to select the plugin in the login call. This must not reference plugins which are not installed as plugins are checked when ICAT performs its initialisation; if plugins are missing ICAT will not start.

authn.<mnemonic>.jndi

is the jndi name to locate the plugin. When you installed the plugin a message would have appeared in the server.log stating the JNDI names. For example for authn_db you would expect to see java:global/authn_db.ear-1.0.0/authn_db.ejb-1.0.0/DB_Authenticator. There must be one such entry for each plugin.

log4j.properties

This is optional. If present it must specify the path to a log4j.properties file. The path may be absolute or relative to the config directory.

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.2.5.ear and install it with the command: asadmin --port 4848 deploy icat.ear-4.2.5.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 database is created. If you already have an ICAT 4.1 or 4.2.n database you may get some messages as it tries to create tables that already exist.

Check that ICAT works

There is one more file in the unpacked icat.ear-4.2.5-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. This connects as one of the root users you defined as 'rootUserNames' in the icat.properties file. Invoke the script with three fixed parameters: the hostname and port on which the service is deployed securely (something like example.com:8181), the mnemonic for the chosen authentication plugin followed by the credentials for one of the root user names supported by that plugin. These credentials should be passed in as pairs of parameters with key followed by value. For example, assuming that your working directory is in the PATH: test.py example.com 8181 db username root password secret

It should report:

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, first erase the directory /tmp/suds and try the test.py again. If it still fails, look at the log files: server.log and icat.log which can both be found in the logs directory below your domain. Look also at the relevant authenticator log.