Difference between revisions of "SmartGears Web Hosting Node (wHN) Installation"

Latest revision as of 11:16, 20 July 2017

Introduction

As described in detail in in the dedicated WIKI Page 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 SmartGears installations.

Prerequisites

The following are prerequisite for a SmartGears installation:

• J2SE 1.8 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 from archived distributions.

• An existing installation of one of the available Servlet Containers, not needed if you use the Distribution Bundle.

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

• A static IP address and preferably a DNS name.

Installation

SmartGears distribution

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 hosting node, 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

SmartGears Distribution Bundle

The SmartGears distribution bundle is a SmartGears Distribution bundled with Apache Tomcat 7 providing a wizard procedure automising the necessary steps reported in the SmartGears Distribution section above.

It is available as a tarball from the gCube Nexus Maven repository, with the following coordinates, make sure you download the tarball from gCube-Releases repository in gCube Nexus Maven repository:

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

Uncompressing the tar.gz would result in the following folder structure under SmartGears-Bundle/:

-- apache-tomcat-7.$version/
-- distro/
-- setup.sh*
-- smartgears-distribution-$version/
-- startContainer.sh*
-- stopContainer.sh*

Please note that $version is a placeholder for the actual version of apache-tomcat and smartgears-distribution you downloaded.

To install the SmartGears Distribution Bundle you should run setup.sh

Usage:  setup.sh [-n <hostname>] [-f | -h] 
 
 
 -n <hostname> = The hostname to set in container.xml
 -f  = Really run the setup. By default it will be a dry-run
 -h  = shows this help.

PLEASE NOTE:

• By default Tomcat will start on 8080 port. If you want to change this port REMEMBER to modify /home/life/SmartGears-Bundle/SmartGears/container.xml consistently

• In configuring the Hosting Node remember that for the production environment the infrastructure name is 'd4science.research-infrastructures.eu' while on the development environment is 'gcube' (with no inverted commas)

• Any Hosting Node cannot join the infrastructure without an authorization token (for each infrastructure context, or scope, it needs to work on). If you don't have a token please contact support_ at_d4science.org

STARTUP and SHUTDOWN SmartGears:

• Please use ./startContainer.sh to startup and ./stopContainer.sh to shutdown (located under SmartGears-Bundle folder)

Configuration

Configuring the Environment

The only environment-level configuration needed by SmartGears is the GHN_HOME variable, as discussed above.

Tomcat Environment

in the case of Tomcat installation some variables can be usefully added to the env. Assuming a bash shell:

export CATALINA_OPTS="-Xmx2000m -Xms2000m"
export CATALINA_PID=~/pid.txt

In some cases it could be needed to increase the maximum permanent generation size, so that the VM can hold additional classes. Assuming a bash shell:

export CATALINA_OPTS="-XX:MaxPermSize=512M"

Configuring the Hosting Node

The runtime configuration of SmartGears is located in the file $GHN_HOME/container.xml.

The following configuration properties are available:

an example of configuration file can be found at [1]

Configuring Logging

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

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 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

SmartGears stores on disk the information it publishes in the gCube Information System, including hosting node and endpoint profiles. In particular:

• the profile of the hosting node is stored in the file $GHN_HOME/state/ghn.xml
• endpoint profiles are stored in files of the following form: $GHN_HOME/state/<app-name>/endpoint.xml

Scripts are available that clean the state of the installation (both node and all or individual endpoint profiles). These scripts can be used when reinstalling SmartGears or during development.

Clean Node State

The script $GHN_HOME/scripts/clean-container-state cleans the entire state of the installation:

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

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

Clean Endpoint State

The script $GHN_HOME/scripts/clean-app-state cleans the state of a single endpoint:

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.