Font size:

Using the ControlTier Installer

Scope
Dependencies
Self Contained Directory Convention
Preparations
Option 1: Using the graphical installer
Option 2: Using the command line based install script
Setting Environment Variables
Start the ControlTier Server web applications
Client-only installation

Scope

This document describes how to install ControlTier server and client using either the ControlTier graphical installer or a command line install script. Although both methods achieve the same result, it is recommended that you use the graphical installer.

Both install methods will setup both the ControlTier server (Workbench, Jobcenter and Reportcenter) and the ControlTier client (CTL and Commander) components on the same local machine. An optional client-only invocation of the install script can be used in distributed environments.

Workbench is a Tomcat based web application that uses a file-based datastore, a WebDAV repository, and (by default) the tomcat-users.xml file for authentication and authorization to provide ControlTier's project design interface.

JobCenter is a Jetty based web application that provides ControlTier web based operational (command execution) interface.

ReportCenter is a Jetty based web application that provides ControlTier web based reporting interface.

CTL is a control-dispatching runtime used to dispatch distributed actions. The ControlTier client includes CTL along with various utilities. CTL uses ssh for remote invocation and communicates with the server via http(s).

Dependencies

ControlTier has 2 dependencies:

Java 1.5 : The install process requires that the latest version of Java 1.5 be installed. You must have the JAVA_HOME environment variable defined in your environment before running either the graphical installer or the install script. See below for instruction on installing Java.
Graphviz (Workbench only) : Graphviz is a visualization software package that must be installed in order to see graphs (command workflows, object relationships, etc.) in the Workbench web interface . It is the only part of the server install that is platform specific. See below for instructions on installing Graphviz. It's also worthing noting that Workbench can function without Graphviz with the consequence being the graphing action will result in a broken image in the graph display area.

Self Contained Directory Convention

The following layout is the best-practice convention that has been adopted as the standard installation layout:

 CTIER_ROOT                                 Defaults to $HOME/ctier on Unix/Linux and C:\ctier on Windows, but is relocatable
      ctl                               CTL_BASE
      demo                                  Optional directory of demonstration applications
      jobcenter                             JOBCENTER_BASE
      reportcenter                          REPORTCENTER_BASE
      pkgs                                  Software installations to support the ControlTier installation
        ControlTier-3.x                     Staging directory for the ControlTier installer
        ctl-0.9.x                       CTL_HOME
        apache-forrest-0.8                  FORREST_HOME
        graphviz-2.xx.x                     GRAPHVIZ_HOME for a Windows installer install
        j2sdk1.5.0_xx                       JAVA_HOME for the ControlTier installation
        jobcenter-x.x.x                     JOBCENTER_HOME
        reportcenter-x.x.x                  REPORTCENTER_HOME
      src                                   Module library source code
      workbench                             CATALINA_BASE and CATALINA_HOME for the ControlTier installation

Some benefits of this layout are:

All package dependencies (beyond the OS installation) are contained within the ControlTier root
The layout consistently separates package software installs from runtime files (HOME vs BASE) facilitating easier upgrade
There's room for multiple demos to be staged (e.g. DukesBank, or PioneerCycling), and the demo directory can be omitted completely to save space.
Appropriate parts of the hierarchy can be culled to produce a minimum client-only install with the same basic structure (e.g. no Tomcat, Forrest or Graphviz)
There's a single well-known location for (ProjectBuilder module and documentation) source code.

Preparations

This section covers installing the dependencies and setting up the self-contained directory structure described in the previous two sections.

These instructions work equally well from a Bash shell on a Unix/Linux system, or on a Windows system using the Command Prompt.

Note

The typographic convention: "$ " (Unix/Linux) and "C:\>" (Windows) is used to indicate the system for which the commands are intended.

The first step is to choose the value of the CTIER_ROOT. For the purpose of these instructions, we assume CTIER_ROOT to have the default value. Avoid choosing a directory that contains spaces since this is not handled reliably throughout the system (this particularly eliminates anything under "C:\Documents and Settings" on Windows).

Create the basic directory structure as per the Self Contained Directory Convention mentioned above:

$ export CTIER_ROOT=~/ctier
$ mkdir -p $CTIER_ROOT/pkgs
        
        
C:\>set CTIER_ROOT=C:\ctier
C:\>mkdir %CTIER_ROOT%\pkgs

On a Unix/Linux system ensure that version 2.x of Graphviz is installed as part of the operating system image:
```
$ which dot
/usr/bin/dot
$ dot -V
dot version 2.2 (Tue Mar 22 18:02:44 UTC 2005)
```
On a Windows system, download the current stable release of the binary distribution of the 2.x version of the Graphviz installer and install it into %CTIER_ROOT%\pkgs as follows. e.g.:

Once the installation has completed, start a new Command Prompt and check Graphviz is available:
```
C:\>dot -V
dot - Graphviz version 2.14.1 (Thu Aug 16 12:22:16 UTC 2007)
		
```
On a Unix/Linux system download the latest self-extracting file version of Sun's 1.5.0 J2SE SDK appropriate for your system into $CTIER_ROOT/pkgs and install it as follows. e.g:
```
$ cd $CTIER_ROOT/pkgs
$ sh j2sdk-1_5_0_15-linux-i586.bin 
.
.
.
Creating j2sdk1.5.0_15/jre/lib/plugin.jar
Creating j2sdk1.5.0_15/jre/javaws/javaws.jar
Done.
```
On a Windows system, download the latest "Offline Installation" version of Sun's 1.5.0 J2SE SDK and install it into %CTIER_ROOT%\pkgs as follows:

Note

Do not register browsers with this version if you do not want to replace your currently installed Java version.
At this point you are ready to proceed with a graphical user (GUI) or command-line interface based installation of the ControlTier software depending your circumstances and preferences.

Option 1: Using the graphical installer

The ControlTier GUI installer is built on the Java-based IzPack installer and should run on any platform supported by that tool.

Download the latest version 3-2 ControlTier Installer executable Jar file into $CTIER_ROOT/pkgs on Unix/Linux:
```
$ cd $CTIER_ROOT/pkgs
$ ls
ControlTier-Installer-3.2.jar  j2sdk1.5.0_15  j2sdk-1_4_2_15-linux-i586.bin
        
```
Or, on Windows into %CTIER_ROOT%\pkgs.
Run the installer from a Linux/Unix shell as follows:

Note

It may be possible to run the Jar by directly clicking on it if you're using a Linux/Unix GUI workstation.

Note

On Linux/Unix the installer is an X Windows client. On a "headless" system it is necessary to set the DISPLAY environment variable appropriately.
```
$ export JAVA_HOME=$CTIER_ROOT/pkgs/j2sdk1.5.0_15
$ $JAVA_HOME/bin/java -jar ControlTier-Installer-3.2-snapshot.jar
        
```
... and on Windows, double-click the installer Jar file:
Select your language preference for install instructions:
After reviewing the introduction screens and accepting the terms of our license agreement select the installation path:

Note

The installation path is the value you chose for CTIER_ROOT.
After selecting the default installation package, review and modify the key installation properties as required:

Note

If you are planning a multi-node installation change the "Tomcat Server Host" value to a fully-qualified domain name or a well know host name.

Note

Change port values if necessary to resolve conflicts on your system making sure you select non-privileged port values (i.e 1024 and beyond).
The remaining dialogs report on installation progress. The standard command-line installer is automatically executed as an external process to complete installation:
With installation complete, the next step is to setup the environment ahead of starting the server web applications.
An uninstaller program is deposited in $CTIER_ROOT for later use:
```
$ ls $CTIER_ROOT/Uninstaller
uninstaller.jar
$ export JAVA_HOME=$CTIER_ROOT/pkgs/j2sdk1.5.0_15
$ $JAVA_HOME/bin/java -jar $CTIER_ROOT/Uninstaller/uninstall.jar
			
```
Note

Forcing deletion will remove the entire contents of CTIER_ROOT from your system including any subsequent project work you may have undertaken.

Option 2: Using the command line based install script

Download and unpack the latest version 3.2 ControlTier Installer Zip file into $CTIER_ROOT/pkgs on Unix/Linux:

$ cd $CTIER_ROOT/pkgs
$ rm -rf ControlTier-3.2
$ unzip ControlTier-3.2.zip
.
.
.
  inflating: ControlTier-3.2/pkgs/jobcenter-1.0.zip  
  inflating: ControlTier-3.2/pkgs/itnav-3.2.war  
  inflating: ControlTier-3.2/pkgs/commander-extension-3.2.jar

Or, on Windows into %CTIER_ROOT%\pkgs:

Review the default.properties file located within the ControlTier installer directory. It is setup to comply with the self-contained directory convention and should not need editing. However, the one change you should make, if you are planning a multi-box ControlTier installation, is to replace the reference to "localhost" with the fully-qualified domain name of your server system (this is not necessary for a single box installation):
```
$ diff default.properties default.properties.orig 
31c31
< server.tomcat.hostname = myhost.mydomain
---
> server.tomcat.hostname = localhost
			
```
Note

You may need to adjust port values and file paths for many of the properties if you are diverging from a standard installation.

Run the installation script located within ControlTier installer directory on Unix/Linux as follows:

$ export JAVA_HOME=$CTIER_ROOT/pkgs/j2sdk1.5.0_15
$ sh install.sh
.
.
.
     [echo]  
     [echo] Install Complete

Setup build successful.

... and on Windows:

C:\ctier\pkgs\ControlTier-3.2>set JAVA_HOME=%CTIER_ROOT%\pkgs\j2sdk1.5.0_15
C:\ctier\pkgs\ControlTier-3.2>set CTIER_ROOT=C:/ctier
C:\ctier\pkgs\ControlTier-3.2>install.bat
.
.
.

Note

It is critical to reset CTIER_ROOT to a Unix/Linux-like value before invoking the installer on Windows!

Setting Environment Variables

On Unix/Linux, a file called .ctierrc was generated in the home directory of the user that ran the install script. This file contains the environment variables that your shell needs to run the ControlTier client and server. Add the following to the user's "~/.bashrc" file::

if [ -f ~/.ctierrc ]; then
   . ~/.ctierrc
else
   echo ~/.ctierrc not found 1>&2
fi

Source ~/.bashrc, or exit and launch a new shell for the changes to take effect.

Note

On Unix/Linux, make sure that .bashrc and .bash_profile files exist and are being sourced correctly. i.e. .bash_profile must source .bashrc which in turn must source .ctierrc

On Windows systems the installer creates a file called ctier.bat in the user's home folder (probably under C:\Documents and Settings). Running this batch file sets the necessary variables and PATH for ControlTier's use:

C:\>"%HOMEPATH%\ctier.bat"
C:\>set CTIER_ROOT=C:\ctier
C:\>set JOBCENTER_HOME=C:\ctier\pkgs\jobcenter-1.0
C:\>set CATALINA_HOME=C:\ctier\workbench
C:\>set CATALINA_BASE=C:\ctier\workbench
C:\>set CTL_HOME=C:\ctier\pkgs\ctl-0.9
C:\>set CTL_BASE=C:\ctier\ctl
C:\>set JAVA_HOME=C:\ctier\pkgs\j2sdk1.5.0_15
C:\>set Path=C:\ctier\pkgs\jobcenter-1.0\bin;C:\ctier\pkgs\ctl-0.9\bin;C:\ctier\workbench\bin;C:\ctier\pkgs\jobcenter-1.0\bin;C:\ctier\pkgs\ctl-0.9\bin;C:\ctier\workbench\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\ctier\pkgs\GRAPHV~1.14\Graphviz\bin;;C:\ctier\pkgs\Graphviz\bin;;C:\ctier\GRAPHV~1.14\Graphviz\bin;;C:\ctier\pkgs\GRAPHV~1.14\Graphviz\bin;;C:\ctier\pkgs\GRAPHV~1.1\Graphviz\bin;"C:\ctier\pkgs\graphviz-2.16\Bin";

Start the ControlTier Server web applications

Reportcenter is started with the following script:

$ start-reportcenter.sh
Starting Reportcenter server...
Server logfile: /home/sitebuild/ctier/reportcenter/logs/reportcenter.log
Stop script: /home/sitebuild/ctier/pkgs/reportcenter-1.0/bin/stop-reportcenter.sh

C:\>start-reportcenter.bat
Starting Reportcenter server...
   Stop script: C:\ctier\pkgs\reportcenter-1.0\bin\stop-reportcenter.bat
18:03:18.250 INFO   [main] org.mortbay.log.LogImpl.add(LogImpl.java:109) >16> added org.mortbay.log.OutputStreamLogSink@30e280
18:03:18.187 INFO   [main] org.mortbay.util.FileResource.<clinit>(FileResource.java:60) >11> Checking Resource aliases
.
.
.
18:04:23.875 INFO   [main] org.mortbay.http.ajp.AJP13Listener.start(AJP13Listener.java:140) >11> NOTICE: AJP13 is not a secure protocol. Please protect the port 0.0.0.0:8010
18:04:23.875 INFO   [main] org.mortbay.util.Container.start(Container.java:74) >09> Started org.mortbay.jetty.Server@26d4f1

Visit the ControlTier Reportcenter URL shown by the install script (e.g. http://localhost:9091/reportcenter).

Workbench is started using the standard Tomcat scripts:

$ startup.sh
Using CATALINA_BASE:   /home/HOSTING/ctier/ctier/workbench
Using CATALINA_HOME:   /home/HOSTING/ctier/ctier/workbench
Using CATALINA_TMPDIR: /home/HOSTING/ctier/ctier/workbench/temp
Using CATALINA_OUT:    /home/HOSTING/ctier/ctier/workbench/logs/catalina.out
Using JAVA_HOME:       /home/HOSTING/ctier/ctier/pkgs/j2sdk1.5.0_15


C:\>startup.bat
Using CATALINA_BASE:   C:\ctier\workbench
Using CATALINA_HOME:   C:\ctier\workbench
Using CATALINA_TMPDIR: C:\ctier\workbench\temp
Using JAVA_HOME:       C:\ctier\pkgs\j2sdk1.5.0_15

Visit the ControlTier Workbench URL shown by the install script (e.g. http://localhost:8080/itnav). The default login/password is default/default.

Jobcenter is started with the following script:

$ start-jobcenter.sh
Starting Jobcenter server...
Server logfile: /home/sitebuild/ctier/jobcenter/logs/jobcenter.log
Stop script: /home/sitebuild/ctier/pkgs/jobcenter-1.0/bin/stop-jobcenter.sh

C:\>start-jobcenter.bat
Starting Jobcenter server...
   Stop script: C:\ctier\pkgs\jobcenter-1.0\bin\stop-jobcenter.bat
18:03:18.250 INFO   [main] org.mortbay.log.LogImpl.add(LogImpl.java:109) >16> added org.mortbay.log.OutputStreamLogSink@30e280
18:03:18.187 INFO   [main] org.mortbay.util.FileResource.<clinit>(FileResource.java:60) >11> Checking Resource aliases
.
.
.
18:04:23.875 INFO   [main] org.mortbay.http.ajp.AJP13Listener.start(AJP13Listener.java:140) >11> NOTICE: AJP13 is not a secure protocol. Please protect the port 0.0.0.0:8010
18:04:23.875 INFO   [main] org.mortbay.util.Container.start(Container.java:74) >09> Started org.mortbay.jetty.Server@26d4f1

Visit the ControlTier Jobcenter URL shown by the install script (e.g. http://localhost:9090/jobcenter). The default login/password is default/default.

Client-only installation

In order to expand your ControlTier infrastructure beyond a single system this section documents how to perform client-only installation using the install scripts.

Though commands can be executed directly on the client systems, one of the benefits of ControlTier is the ability to use SSH for remote command execution. The CTL framework property file ($CTL_BASE/etc/framework.properties, or %CTL_BASE%\etc\framework.properties) contains a property called "framework.ssh.user" that defaults to the user name of the account used to run the installer. The recommended scheme is to use this account consistently across your network and use SSH public key authentication (DSA key files by default) to equivalence all the client systems to the server to provide a centralized point of administration.

Note

Windows users should note that this reliance on SSH requires third-party software be installed for distributed execution. We recommened the copSSH packaging of OpenSSH.

The first step is to choose the value of the CTIER_ROOT. For the purpose of these instructions, we assume CTIER_ROOT to have the default value. Once again, avoid choosing a directory that contains spaces since this is not handled reliably throughout the system (this particularly eliminates anything under "C:\Documents and Settings" on Windows).

Note

Though not strictly necessary, we recommend you use the same CTIER_ROOT for each client as used on the server. As noted, you must use the user account specified by the framework.ssh.user property in the server's framework property file if you plan to use SSH from the server for centralized administration.

Create the basic directory structure as per the Self Contained Directory Convention mentioned above:

$ export CTIER_ROOT=~/ctier
$ mkdir -p $CTIER_ROOT/pkgs
        
        
C:\>set CTIER_ROOT=C:\ctier
C:\>mkdir %CTIER_ROOT%\pkgs

Note

Though we strive for backward compatibility, we recommend you keep software versions of the client and server systems aligned.

On a Unix/Linux system download the latest self-extracting file version of Sun's 1.5.0 J2SE SDK appropriate for your system into $CTIER_ROOT/pkgs and install it as follows. e.g:
```
$ cd $CTIER_ROOT/pkgs
$ sh j2sdk-1_5_0_15-linux-i586.bin 
.
.
.
Creating j2sdk1.5.0_15/jre/lib/plugin.jar
Creating j2sdk1.5.0_15/jre/javaws/javaws.jar
Done.
					
```
On a Windows system, download the latest "Offline Installation" version of Sun's 1.5.0 J2SE SDK and install it into %CTIER_ROOT%\pkgs as follows:

Note

Do not register browsers with this version if you do not want to replace your currently installed Java version.

Download and unpack the latest version 3.2 ControlTier Installer Zip file into $CTIER_ROOT/pkgs on Unix/Linux:

$ cd $CTIER_ROOT/pkgs
$ rm -rf ControlTier-3.2
$ unzip ControlTier-3.2.zip
.
.
.
  inflating: ControlTier-3.2/pkgs/jobcenter-1.0.zip  
  inflating: ControlTier-3.2/pkgs/itnav-3.2.war  
  inflating: ControlTier-3.2/pkgs/commander-extension-3.2.jar

Or, on Windows into %CTIER_ROOT\pkgs:

Copy the "site master" copy of framework.properties (i.e. the one used to install your server) to the ControlTier installer directory on the client. The file will remain largely unchanged, however make sure that the server.tomcat.hostname property is set to the hostname (or, more often, the fully qualified domain name) of the server, and that the client.hostname property is set to the hostname or fully qualified domain name of the client (as it is known to the server).

Run the installation script located within ControlTier installer directory with the "-client" option on Unix/Linux as follows. e.g:

$ export JAVA_HOME=$CTIER_ROOT/pkgs/j2sdk1.5.0_15
$ sh install.sh -client
.
.
.
     [echo]  
     [echo] Install Complete

Setup build successful.

... and on Windows:

C:\ctier\pkgs\ControlTier-3.2>set JAVA_HOME=%CTIER_ROOT%\pkgs\j2sdk1.5.0_15
C:\>set CTIER_ROOT=C:/ctier
C:\ctier\pkgs\ControlTier-3.2>install.bat -client
.
.
.

Note

It is critical to reset CTIER_ROOT to a Unix/Linux-like value before invoking the installer on Windows!

Follow the Setting Environment Variables section above to setup the necessary environment requirements.
You are now ready to register the new client node with an existing project using the ctl-depot command.