DEPRECATED - REMOVE IT SmartGears gHN Installation

Introduction

As described in detail in in the dedicated section of the gCube Developer's Guide, SmartGears is a set of Java libraries that turn Servlet-based containers and applications into gCube resources, in a transparent way.

In this guide, we show how administrators and site-managers can install SmartGears and manage the installation.

Prerequisites

The following are prerequisite for a SmartGears installation:

• J2SE 1.6 update 4 SDK or greater. Oracle's reference implementation is recommended, but versions from IBM, HP, or BEA should work equally well.

• GNU tar to install the SmartGears gHN from archived distributions.

• An existing installation of one of the available Servlet Containers

The following are pre-requisites for the operation of a SmartGears-based gHN in any infrastructure:

• A static IP address and preferably a DNS name.

Installation

The SmartGears distribution is available as a tarball from the [|gCube Nexus Maven repository], with the following coordinates:

<dependency>
  <groupId>org.gcube.distribution</groupId>
  <artifactId>smartgears-distribution</artifactId>
  <version>...</version>
  <type>tar.gz</type>
</dependency>

Once downloaded, the tarball can be expanded in any location of the filesystem, henceforth referred to as the installation folder. The distribution contains all the relevant files, including the install script which performs the real installation of SmartGears within the servlet container.

A new folder should be designated to contain the state of the SmartGears-enabled gHN, and its absolute path configured as the value of the GHN_HOME environment variable. If the folder, does not exist, the install script will create it.

usage:  install [-d <distro directory>] -s tomcat|<lib directory> -a [app directory] [-g gHN directory] [-x|-h] 

  <distro directory> = the directory with the distribution of SmartGears XXX.
                       By default, this is the parent directory of this script.
  <lib directory>    = the directory with libraries shared by all applications in the target container.
  <app directory>    = the directory with all the applications in the target container.
  <gHN directory>    = the directory with logs and files related to the gCube Hosting Node.
                       By default, this is value of the GHN_HOME env var.
  tomcat             = Sets <lib directory> and <app directory> for a target Tomcat container.
  x                  = dry run.
  h                  = shows this help.

The following parameters must be provided to the script for each servlet container:

• -a <app directory> : is the folder where applications are stored in the container
• -s <lib directory> : is the folder where the shared libraries of the container are stored.

In the common case in which the servlet container is Tomcat, however, the single setting:

• -s tomcat

will suffice, provided the environment variable CATALINA_HOME is correctly set.

Other optional parameters include:

• -s <distro directory>: specifies the folder where the Smargears distribution has been downloaded.
• -g <gHN directory> : specifies the gHN folder if not provided trough GHN_HOME var
• -x : perform a dry run : checks that the specified options are fine without performing a real installation

Upgrade

An existing SmartGears installation can be upgraded with the download script, which contacts the gCube Nexus Repository. The script is available in $GHN_HOME/scipts/download<code> and it offers the following options:

usage:  download [-v <version>] [-o <folder>] [-s|-h] 

  <version>          = the version to download.
                     = By default, this is the latest known version.
  s                  = download a snapshot version.
  <folder>           = download to specific folder.
  h                  = shows this help.

Clean

The SmartGears gHN serialises locally on the disk the information published on the gCube Information system ( gHN and RunningInstance profiles), in particular:

• gHN profile is serialised in the file $GHN_HOME/state'/ghn.xml
• Apps profiles are serialised in the file $GHN_HOME/state/<app-name>/endpoint.xml

scripts are available in order to clean the state of the gHN ( both gHN and single app) and it quite useful in the case of reinstallation or development.

Clean gHN state

The script $GHN_HOME/scripts/clean-container-state can be used in order to clean the whole gHN state:

usage:  clean-container-state  [-g <ghn_home>] [-h] 

  <ghn_home>   = the gHN directory.
  h             = shows this help.

Clean App state

The script $GHN_HOME/scripts/clean-app-state can be executed in order to clean the state of a single app:

usage:  clean-app-state -a <app_name> [-g <ghn_home>] [-h] 

  <app-name>    = the application name whose state has to be cleaned
  <ghn_home>    = the gHN directory.
  h             = shows this help.

Configuration

Configuring the Environment

The only environment configuration needed by the SmartGears gHN is the location of the gHN home folder, therefore the environment should be properly configured to set the GHN_HOME var to point to that folder.

Configuring the gHN

The configuration of the SmartGears gHN that relates to its operation within the infrastructure can be found in <code>$GHN_HOME/container.xml.

The following properties are available for configuration:

mode	either offline or online depending on whether the gHN does or does not publish information in the infrastructure.
hostname	the hostname of the container to be published on the infrastructure.
port	the port of the container to be published on the infrastructure.
infrastructure	the name of the infrastructure in which the gHN operates. (e.g. gcube, d4science,...).
vo	the VO[s] that the gHN joins.
persistence	an alternative folder where the gHN and apps state are maintained.
property	an arbitrary property with name/value attributes
country	the two-character ISO code of the Country where the gHN is located.
location	the name of the location.
longitude	the longitude of the gHN.
latitude	the latitude of the gHN.
publication-frequency	how often the gHN has to refresh its profile on the IS (in seconds).

an example of container descriptor can be found at [1]

Configuring Logging

Please refer to the SmartGears development guide section on logging [2]

Supporting resource encryption/decryption

TO DO