ZIP installer

From ControlTier

Revision as of 12:43, 2 January 2011 by Hiran (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The command line installer is a Zip archive containing the ControlTier server and client software. It also contains a defaults file and a Unix and Windows install script.

The installer is comprised of a distribution that includes an install script, file and the content of the distribution.


Server+Client vs Client-only

The install script contained in the installer can be used to install both server and client or just the client software. The default is to install both. You might be interested to use ZIP installer (multiple-clients) to use the Zip installer to install client software across multiple hosts.

You also have to think of where you want ControlTier to be installed. This is set with the CTIER_ROOT environment variable.


Download and extract the latest version ControlTier Installer Zip file. These are located in the Sourceforge project.


Extract the archive into $CTIER_ROOT/pkgs.


$ export CTIER_ROOT=~/ctier
$ mkdir -p $CTIER_ROOT/pkgs
$ cd $CTIER_ROOT/pkgs
$ rm -rf ControlTier-<version>
$ unzip ControlTier-<version>.zip
  inflating: ControlTier-3.2/pkgs/  
  inflating: ControlTier-3.2/pkgs/itnav-3.2.war  
  inflating: ControlTier-3.2/pkgs/commander-extension-3.2.jar  

Substitute your version of the ControlTier installer.


From the windows file browser, select the installer zip archive and right click it to select the extract action. Be sure to choose your %%CTIER_ROOT%%\pkgs folder:


Specifying and overriding defaults

The installer is driven by a number of settings in the file located within the ControlTier installer directory. It is setup to comply with the self-contained directory convention and should not need editing. However, you may want to specify the hostname to use for you server or client installation.

The current Operating System hostname is used as the default server hostname for Server installations. It is also used as the default client hostname for Client-only installations.

$ diff 
< server.hostname = myhost.mydomain
> server.hostname = ${server.hostname.default}

Alternatively, you can use the "-Dkey=val" pairs to override these defaults from the command line. Eg

sh ./

You can actually override any setting in the file in this same way, using -Dkey=val flags. See INSTALL Command Reference

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

Option to automatically create a default project

If you plan to run the ControlTier Demo, the installer can optionally create a project called "demo" during your first login. The following example enables this option:

 sh ./ -Dproject.default.create=true

If you are not running the demo, but you wish to have an empty project to start working in, you may also specify the initial project's name by overriding the property The following example sets the name to "myProject":

  sh ./ -Dproject.default.create=true

For ControlTier 3.6:

  sh ./ -Dframework.project.default.create=true

Note that it can take from 3 - 10 minutes for Workbench to create its initial project when you first log in.

Run installation script

Run the installation script located within ControlTier installer directory


To install the server and client software based on the defaults run:

$ export JAVA_HOME=$CTIER_ROOT/pkgs/j2sdk1.5.0_15

... or on a Mac:

$ export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home

Then change to the directory where you extracted the distribution and run the installer:

$ cd $CTIER_ROOT/pkgs/ControlTier-3.2
$ sh
     [echo] Install Complete

Setup build successful.


The basic client install process is done in two steps:

  1. Change directory to the directory created after unzipping the ZIP installer. Eg,
    • cd /path/to/extracted/ControlTier-3.4.6.
  2. Install the client software specifying the "--client" flag. Eg,
    • sh ./ --client -Dserver.hostname=<> -Dclient.hostname=<>

The install supports commandline overrides of all properties from the file.

Specify a property value using "-Dkey=val" on the commandline.

Required Properties

You will need to specify the server hostname via "-Dkey=val" overrides:

Optional Properties

Here's the basic usage pattern:

sh --client -Dserver.hostname=<server hostname> -Dclient.hostname=<hostname><name>

Here's an example that specifies the server host as "strongbad" and the client host as "centos2":

sh --client -Dserver.hostname=strongbad -Dclient.hostname=centos2

By default the hostname command will be used for the values of client.hostname and, so those can be elided if you want:

sh --client -Dserver.hostname=strongbad

Equivalent to:

sh --client -Dserver.hostname=strongbad -Dclient.hostname=`hostname``hostname`

You'll see a bunch of messages printed to the console but you will see output resembling this:

     [echo] Using compatible Java version: 1.5
. <output omitted>
     [echo] A .ctierrc file was generated at:
     [echo]     /home/demo/.ctierrc
     [echo] containing the appropriate environment variables for the installed
     [echo] ControlTier Client To use it, add the following to your .profile
     [echo] or equivalent:
     [echo]     if [ -f ~/.ctierrc ]; then
     [echo]     . ~/.ctierrc
     [echo]     else
     [echo]     echo ~/.ctierrc not found 1>&2
     [echo]     fi

     [echo] Install Complete

Setup build successful.

The last few lines show the installation occurred without errors. Also note, the message bout the ".ctierrc" file. See ControlTier Environment Variables.

Often times, one installs a client for the purpose of defining it as a Node it in a specific project. There are two defaults settings you can use to define that:

Here's the general install command usage pattern using those settings:

sh --client -Dserver.hostname=<server host> \
    -Dclient.hostname=<client host><client host> \<project name> -Ddepot.default.create=<boolean>

Here's an example that will register the client as the "centos2" Node to the project named "demo":

sh --client -Dserver.hostname=strongbad \
    -Dclient.hostname=centos2 \ -Ddepot.default.create=true

If you are installing multiple clients take a look at the Bulk client installation page.


It is critical to reset CTIER_ROOT to a Unix/Linux-like value before invoking the installer 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

To install the just the client run:

install.bat --client -Dserver.hostname=<hostname>

Runtime Environment variables



On Unix/Linux, a file called .ctierrc will be generated in the home directory of the user that runs the ControlTier installer. This file contains the environment variables that your shell needs to run the ControlTier client and server.

Add the following to your shell profile (e.g. "$HOME/.bashrc"). Be sure the shell profile you choose is read for both interactive and non-interactive shells, so "$HOME/.profile" may not be a good choice.

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

Source ~/.ctierrrc, for the settings to take immediate effect.

$ . ~/.bashrc

Bash users

Bash users should source the .ctierrc file from their .bashrc file. Quoting from the bash man page:

Bash attempts to determine when it is being run by the remote shell daemon, in this case sshd. If bash determines it is being run by sshd, it reads and executes commands from ~/.bashrc, if that file exists and is readable.

The .bashrc file is read during remote SSH connections which are non-interactive. The .bash_profile is only read for interactive logins. The .bash_profile can in turn source the .bashrc file. Here's a recommended ordering for the file sourcing:

.bash_profile → .bashrc → .ctierrc

See the bash man page for more information. The Bash Startup Files section gives an in depth explanation.


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:\>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";


Be sure the PATH includes the executables in $CTL_HOME/bin otherwise you might see an error like so:

bash: ctl: command not found

Sourcing the .ctierrc file should insure the PATH is set correctly. Check remote hosts like so:

ssh remotehost which ctl

Be sure a path is returned otherwise, the PATH is not set correctly.

Server start

Unix Start

Within the Jetty install is a "" script used to manage the Jetty process. This should already be set in your PATH. (ie, PATH=$PATH:$JETTY_HOME/bin)

Use the "start" sub-command:

$ start
Starting Jetty: STARTED Jetty Tue Dec 23 16:07:29 PST 2008
2008-12-23 16:07:30.659::INFO:  Logging to STDERR via org.mortbay.log.StdErrLog
2008-12-23 16:07:30.726::INFO:  Redirecting stderr/stdout to /Users/alexh/ctier/pkgs/jetty-6.1.10/logs/2008_12_24.stderrout.log

Windows Start

Within the Jetty install is a "start.bat" script used to start the Jetty process. You'll find it as %JETTY_HOME%\bin\start.bat.


The install also includes a Jetty-Service.exe documented here Win32Wrapper.


Already Running

You might see this error even if there is no JVM process:

$ start
Starting Jetty: Already Running!!

Just run the "stop" command and then run the "start" command again.

Solaris:start-stop-daemon: command not found

Running " start" you might see this error on Solaris:

Starting Jetty: /export/home/alexh/ctier/pkgs/jetty-6.1.10/bin/ line 497: whoami: command not found
/export/home/alexh/ctier/pkgs/jetty-6.1.10/bin/ line 499: start-stop-daemon: command not found

This is due to the Solaris "which" command. The hack work around is to make the following change in

< 	if which start-stop-daemon > /dev/null 2>&1 
> 	if false

Verify installation

After you have run the installer and have made provisions for the setting the environment (e.g., sourced ~/.ctierrc) you should verify the installation.

Firstly, check that the CTL shell tools are in your path. Type:

ctl --help
usage: ctl [-h] [-v] [-V] [-z] [-p project -t type -r resource -c command] [-p
           project -m module -c command] [--threadcount <1>] [-I filter] [-X filter]
           [--filter-exclude-precedence true/false][-l level] [-- command-options]
[3.6.0 (20100915)]

You should see the help output and the version on the last line. If you get a "command not found" error. Double check that your login environment is set up correctly.


After you have started the ControlTier server you can try logging in to Workbench (default URL will be http://localhost:8080 unless you changed the setting in the installer).

The initial landing page will provide a set of links to the server applications. Below this list you will see information about login IDs. The installation will have created a number of default accounts. Begin by logging into Workbench with the default ID (set by the installer to user: "default" and password: "default" unless you changed that setting).

Login denied?

If these default credentials do not work, check the file $CTIER_ROOT/pkgs/jetty-6.1.21/etc/ as it shows the available users. If your account is there (and you are sure about the correct password), check the log files $CTIER_ROOT/pkgs/jetty-6.1.21/logs. If you find this message

java.lang.RuntimeException: config file did not contain property: ctl.base

you probably started jetty without having set the proper environment first.

Personal tools