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 you use the graphical installer.

Both install methods will setup both the ControlTier server (Workbench and Jobcenter) and the ControlTier client (Antdepo 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.

The ControlTier client is a stand-alone java application that embeds AntDepo (an Ant-based runtime). It uses ssh for remote invocation and communicates with the server via http(s).

ControlTier has 3 dependencies:

• Java 1.4 : The install process requires that the latest version of Java 1.4 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.
• Tomcat 4.1 :The server requires that a working copy of the latest version of Tomcat 4.1.30 be installed in your system. See below for instructions on installing Tomcat.
• Graphviz :Graphviz is a visualization software package that must be installed in order to see graphs (command workflows, object relationships, etc.) in the ControlTier server web interface or in the ControlTier client. It is the only part of the server install that is platform specific. See below for instructions on installing Graphviz.

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
      antdepo                               ANTDEPO_BASE
      demo                                  Optional directory of demonstration applications
      jobcenter                             JOBCENTER_BASE
      pkgs                                  Software installations to support the ControlTier installation
        ControlTier-3.x                     Staging directory for the ControlTier installer
        antdepo-1.x.x                       ANTDEPO_HOME
        apache-forrest-0.8                  FORREST_HOME
        graphviz-2.xx.x                     GRAPHVIZ_HOME for a Windows installer install
        j2sdk1.4.2_xx                       JAVA_HOME for the ControlTier installation
        jobcenter-x.x.x                     JOBCENTER_HOME
      src                                   Module library source code
      workbench                             CATALINA_BASE and CATALINA_HOME for the ControlTier installation    	
		

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. Headlines, 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 Tomcat, 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.4.2 J2SE SDK appropriate for your system into $CTIER_ROOT/pkgs and install it as follows. e.g:

   $ cd $CTIER_ROOT/pkgs
   $ sh j2sdk-1_4_2_16-linux-i586.bin 
   .
   .
   .
   Creating j2sdk1.4.2_16/jre/lib/plugin.jar
   Creating j2sdk1.4.2_16/jre/javaws/javaws.jar
   Done.
   

   On a Windows system, download the latest "Offline Installation" version of Sun's 1.4.2 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 ControlTier Installer executable Jar file into $CTIER_ROOT/pkgs on Unix/Linux:

   $ cd $CTIER_ROOT/pkgs
   $ ls
   ControlTier-Installer-3.1-rc2-snapshot.jar  j2sdk1.4.2_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.4.2_15
   $ $JAVA_HOME/bin/java -jar ControlTier-Installer-3.1-rc2-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 values if necessary to resolve conflicts on your system making sure you select non-privileged port values (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.4.2_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 ControlTier Installer Zip file into $CTIER_ROOT/pkgs on Unix/Linux:

   $ cd $CTIER_ROOT/pkgs
   $ rm -rf ControlTier-3.1
   $ unzip ControlTier-3.1.zip
   .
   .
   .
     inflating: ControlTier-3.1/pkgs/jobcenter-0.5.zip  
     inflating: ControlTier-3.1/pkgs/itnav-3.1.war  
     inflating: ControlTier-3.1/pkgs/commander-extension-3.1.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.4.2_16
   $ sh install.sh
   .
   .
   .
        [echo]  
        [echo] Install Complete
   
   Setup build successful.
           

   ... and on Windows:

   C:\ctier\pkgs\ControlTier-3.1>set JAVA_HOME=%CTIER_ROOT%\pkgs\j2sdk1.4.2_16
   C:\ctier\pkgs\ControlTier-3.1>set CTIER_ROOT=C:/ctier
   C:\ctier\pkgs\ControlTier-3.1>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 JOBCENTER_HOME=C:\ctier\pkgs\jobcenter-0.5
C:\>set CATALINA_HOME=C:\ctier\workbench
C:\>set CATALINA_BASE=C:\ctier\workbench
C:\>set ANTDEPO_HOME=C:\ctier\pkgs\antdepo-1.3.1-rc1
C:\>set ANTDEPO_BASE=C:\ctier\antdepo
C:\>set JAVA_HOME=C:\ctier\pkgs\j2sdk1.4.2_14
C:\>set Path=C:\ctier\pkgs\jobcenter-0.5\bin;C:\ctier\pkgs\antdepo-1.3.1-rc1\bin;C:\ctier\workbench\bin;C:\ctier\pkgs\jobcenter-0.5\bin;C:\ctier\pkgs\antdepo-1.3.1-rc1\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";
	

1. 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.4.2_16
   
   
   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.4.2_14
     

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

2. 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-0.5/bin/stop-jobcenter.sh
   
   C:\>start-jobcenter.bat
   Starting Jobcenter server...
      Stop script: C:\ctier\pkgs\jobcenter-0.5\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.

As a next step we recommend you try out ControlTier tutorials.

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 Antdepo framework property file ($ANTDEPO_BASE/etc/framework.properties, or %ANTDEPO_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.4.2 J2SE SDK appropriate for your system into $CTIER_ROOT/pkgs and install it as follows. e.g:

   $ cd $CTIER_ROOT/pkgs
   $ sh j2sdk-1_4_2_16-linux-i586.bin 
   .
   .
   .
   Creating j2sdk1.4.2_16/jre/lib/plugin.jar
   Creating j2sdk1.4.2_16/jre/javaws/javaws.jar
   Done.
   					

   On a Windows system, download the latest "Offline Installation" version of Sun's 1.4.2 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 ControlTier Installer Zip file into $CTIER_ROOT/pkgs on Unix/Linux:

   $ cd $CTIER_ROOT/pkgs
   $ rm -rf ControlTier-3.1
   $ unzip ControlTier-3.1.zip
   .
   .
   .
     inflating: ControlTier-3.1/pkgs/jobcenter-0.5.zip  
     inflating: ControlTier-3.1/pkgs/itnav-3.1.war  
     inflating: ControlTier-3.1/pkgs/commander-extension-3.1.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.4.2_16
   $ sh install.sh -client
   .
   .
   .
        [echo]  
        [echo] Install Complete
   
   Setup build successful.
           

   ... and on Windows:

   C:\ctier\pkgs\ControlTier-3.1>set JAVA_HOME=%CTIER_ROOT%\pkgs\j2sdk1.4.2_16
   C:\>set CTIER_ROOT=C:/ctier
   C:\ctier\pkgs\ControlTier-3.1>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 depot-setup command.