Using the ControlTier Installer

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 new users try the graphical installer.

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

Workbench is a web application that serves as a project design, CMDB and package repository.

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

ReportCenter is a 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).

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

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
         src                                Module library source code
      demo                                  Optional directory of demonstration applications
      jobcenter                             JOBCENTER_BASE
      reportcenter                          REPORTCENTER_BASE
      workbench                             Workbench runtime files
      jackrabbit                            Apache Jackrabbit file repository data
      pkgs                                  Software installations to support the ControlTier installation
        ControlTier-3.x                     Staging directory for the ControlTier installer
        ctl-1.x.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
        jetty-6.x.x                         JETTY_HOME
		

Some benefits of this layout are:

1. All package dependencies (beyond the OS installation) are contained within the ControlTier root
2. The layout consistently separates package software installs from runtime files (HOME vs BASE) facilitating easier upgrade
3. 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.
4. Appropriate parts of the hierarchy can be culled to produce a minimum client-only install with the same basic structure (e.g. no Jetty, Forrest or Graphviz)
5. There's a single well-known location for (ProjectBuilder module and documentation) source code.

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.

1. 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).

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

3. 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)
   		

4. 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.
5. 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.

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

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

2. 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:

   

3. Select your language preference for install instructions:

   

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

5. 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 value if necessary to resolve conflicts on your system making sure you select a non-privileged port value (i.e 1024 and beyond).
   

6. The remaining dialogs report on installation progress. The standard command-line installer is automatically executed as an external process to complete installation:

   

7. With installation complete, the next step is to setup the environment ahead of starting the server web applications.

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

1. 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:

   

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

3. 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!

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.

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 JETTY_HOME=C:\ctier\pkgs\jetty-6.1
C:\>set CTL_HOME=C:\ctier\pkgs\ctl-1.1
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-1.1\bin;C:\ctier\workbench\bin;C:\ctier\pkgs\jobcenter-1.0\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";
	

1. The ControlTier server applications runs inside a common Jetty instance started with the following script:

   $ $JETTY_HOME/bin/jetty.sh start
   Server logfile:/home/ctier/ctier/pkgs/jetty-6.1.10/logs/reportcenter.log
   ...
   
   

   Or on Windows:

   C:\>%JETTY_HOME%\bin\start.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 Server homepage URL shown by the install script (e.g. http://localhost:8080/). This homepage contains links to each of the ControlTier web applications running in the Jetty instance.

   

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.

1. 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.
2. 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
   					

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

4. 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:

   

5. 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).

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

   ... 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!
7. Follow the Setting Environment Variables section above to setup the necessary environment requirements.
8. You are now ready to register the new client node with an existing project using the ctl-depot command.