TeamForge CLI Server Installation

The Digital.ai TeamForge CLI Server runs CLI scripts on the TeamForge server as extensions to the platform. This page covers the system requirements, the installation procedure, and the bundled test program that verifies the install.

For information about writing and uploading scripts once the server is installed, see the CLI Server User Guide.

System Requirements​

The CLI Server requires the following supported TeamForge versions and tools.

• TeamForge 6.1 to 6.2.0.x, on Red Hat or CentOS Linux
• TeamForge CLI 1.5
• Customization Installer 3.9.0.0

The following third party tool is required.

• mod_fcgid version 2.2, release 11.el5

Installation​

Complete the prerequisites, then install the CLI and the CLI Server.

Prerequisites​

TeamForge configuration

This install assumes a native Linux install of TeamForge configured to use a fully qualified domain name (FQDN) as defined in the site-options.conf file. To verify that this is configured properly, run the following command as root.

grep webserver.root-url /etc/sourceforge.properties

The URL that property points to should work when you paste it into your browser.

Customization Installer

The TeamForge customization installer manages the deployment of all add-on tools applied to a TeamForge site. Download and install, via RPM, the installer for your platform.

mod_fcgid

The CLI Server depends on the mod_fcgid Apache module, which manages the persistent state of the CLI as a server process. This module is available on the EPEL Yum server.

wget http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm
rpm -i epel-release-5-4.noarch.rpm
yum install mod_fcgid

The recommended approach is to add the EPEL repository as a Yum server so that any other missing dependencies are detected and installed for you. However, if your TeamForge site does not have direct internet access, you can download the mod_fcgid module directly.

CLI

Install the TeamForge CLI via RPM for your platform. Once installed via RPM, no other setup steps are needed for the CLI itself.

Install the CLI Server​

Download and install the CLI Server package appropriate for your platform. Once the RPM is installed, change to the CLI Server directory.

cd /opt/collabnet/teamforge/add-ons/teamforge_cli_server

In the install directory, type custom-install to complete the installation. The installer prompts for a site administrator username and password so that it can make branding updates and configure the CLI Server in the Integration Data Service.

When the install is complete, restart Apache and start the CLI Server.

service httpd restart
service teamforge_cli_server start

Note on SSL Certificates​

If your site is protected by an untrusted SSL certificate, either because it is self signed, uses a private certificate authority, or has expired, you must add that certificate to the local Java keystore. If you are unsure about the status of your SSL certificate, contact support for help.

Testing the Install​

The installation directory contains a program that tests the installation and exercises the CLI Server features. Make sure that TeamForge, Apache, and the CLI Server are all active, then run the test program. The results should look as follows.

Package install test                  => Pass
Is CTF Running?                       => Pass
Is Apache Running?                    => Pass
Is CTF API ready?                     => Pass
SE Linux compatability                => Pass
Testing Database connection           => Pass
Getting SOAP Admin Session Key        => Pass
Checking CTF getVersion call          => Pass
CLI Server Apache rules               => Pass
Apache include for CLI Server         => Pass
Checking overrides dir                => Pass
SVN Status of cliserver/cli dir       => Pass
SVN Status of overrides dir           => Pass
Checking Permissions (fcgi)           => Pass
Checking Server owner (should be 0)   => Pass
Checking Server group (should be 0)   => Pass
Is CLI Cron daemon running?           => Pass
Is Java Event Handler loaded?         => Pass
CLI Server test                       => Pass
Preparing CLI cron test, this may take a few minutes...
..
CLI Cron test                         => Pass
.
CLI Event test                        => Pass

The following sections describe what each test does and what to check if it fails.

Package Install Test​

This test runs the custom-install program with the --list option and looks for teamforge_cli_server in the results. If this test fails, custom-install has not yet been run and the CLI Server is not installed.

Is CTF Running​

This is a simple test to see whether TeamForge is listening on port 8080 on localhost. If this test fails, TeamForge is not running.

Is Apache Running​

This test checks that Apache is running on port 80, or on port 443 if SSL is enabled in site-options.conf.

Is CTF API Ready​

When TeamForge starts, the SOAP API takes a little more time to be ready than the main startup script waits for. If this test fails, TeamForge most likely needs a bit more time to finish starting up.

SE Linux Compatibility​

The CLI Server is not enabled for sites that enforce SE Linux rules. If this test fails, the server is configured to enforce SE Linux rules.

Testing Database Connection​

Portions of the CLI Server need to connect directly to the TeamForge database. Those settings are taken from the teamforge/runtime/con/runtime-options.conf file, which is the same file the TeamForge installer uses to configure TeamForge access to the database. If this test fails, either the database is not running or those settings are not correct.

Getting SOAP Admin Session Key​

The CLI Server cron process uses the site administrator account to interact with the system. It gets a SOAP session key automatically by temporarily resetting the admin password to a random one that only it knows, and then putting the original password back in place. If this test fails, it could be because the TeamForge license is expired or invalid, or the site administrator account has been disabled.

Checking CTF getVersion Call​

This is a simple API test done as a secondary verification that the admin session key is working.

CLI Server Apache Rules​

Apache manages the main CLI Server process. The configuration for Apache should be in the Apache conf.d directory in the cliserv.conf file. If this test fails, the file is missing, which implies a failure during the install process. Check the install log for the CLI Server and look for the httpd/conf.d to /etc/httpd/conf.d section.

/opt/collabnet/teamforge/log/add-ons/teamforge_cli_server.log

Apache Include for CLI Server​

The main Apache config file needs an Include line that tells Apache to load the cliserv.conf file when it starts. Depending on how your TeamForge site was installed, that line takes one of two forms.

Include conf.d/cliserv.conf
Include conf.d/*.conf

If this test fails, one of the two lines above is missing. See the install log for details on why this may have failed.

Checking Overrides Dir​

At install time, new branding content is loaded via Subversion. That content should have been mirrored to the teamforge/var/cliserver directory tree. This test checks that the first time cron script is there.

cliserver/cli/cron/once/setupLook.ctf

This test fails if that file is missing. That implies that either there was a problem loading the branding content, someone removed the setup script, or the branding mirroring script failed. Check the svn status as the Apache user and make sure the directory is clean. svn status should return nothing. Similarly, svn info . should report the directory as a working copy from the local branding repository, with the most recent revision number.

# su - apache
-sh-4.1$ cd /opt/collabnet/teamforge/var/cliserver/cli
-sh-4.1$ svn status
-sh-4.1$

-sh-4.1$ svn info .
Path: .
Working Copy Root Path: /opt/collabnet/teamforge/var/cliserver/cli
URL: file:///sf-svnroot/branding/cli
Repository Root: file:///sf-svnroot/branding
Repository UUID: 016c8eed-1ede-4c92-8829-6eba15d81910
Revision: 280
Node Kind: directory
Schedule: normal
Last Changed Author: admin
Last Changed Rev: 280
Last Changed Date: 2013-02-01 18:34:19 -0500 (Fri, 01 Feb 2013)

SVN Status of cliserver/cli Dir​

The teamforge/var/cliserver/cli directory is a checked out working copy of the /cli tree in the branding repository. This test ensures that svn status runs cleanly. If this test fails, it implies there is content in that directory that is not in the branding repository, which could impede the ability of users to use Subversion to update the CLI Server. It is important that svn status returns no results when run as the Apache user.

SVN Status of Overrides Dir​

This is the same test as above, but with the teamforge/var/overrides directory.

Checking Permissions (fcgi)​

Apache invokes the main CLI Server process using the mod_fcgid module. This test verifies that the permissions on the CLI Server program are correct. The test expects the following result to pass.

# ls -l /var/www-local/fcgi-bin/cliserver.fcgi
-rwsr-xr-x 1 root root 6951 Jul  2  2012 /var/www-local/fcgi-bin/cliserver.fcgi

Checking Server Owner (Should Be 0)​

The CLI Server fcgi program should be owned by root for this test to pass.

Checking Server Group (Should Be 0)​

The CLI Server fcgi program should be in the root group for this test to pass.

Is CLI Cron Daemon Running​

This is a simple test to make sure the CLI Server cron daemon is running. It takes the process id from /var/run/cli/server and sends a 0 signal to the process. If the test fails, it is either because the run file is missing, the PID in that file is wrong, or the process is not running.

Is Java Event Handler Loaded​

This test checks the listCustomEventHandlers page in the TeamForge web UI to see whether it can find cli-server.jar in the list of loaded event handlers. This test does not run if your site options file disables that page. The parameter is ENABLE_UI_FOR_CUSTOM_EVENT_HANDLERS.

If that value is true and the test fails, the handler was not loaded properly. Look at the install log to make sure the cli-server.jar file was deployed properly. Also check the events directory to make sure it is readable by the TeamForge user and that the cli-server.jar file is readable.

# ls -ld /opt/collabnet/teamforge/var/events
drwxr-xr-x 2 sf-admin sf-admin 4096 Jan 30 16:51 /opt/collabnet/teamforge/var/events

# ls -l /opt/collabnet/teamforge/var/events/cli-server.jar
-rw-r--r-- 1 root root 7259 Jan 30 17:09 /opt/collabnet/teamforge/var/events/cli-server.jar

CLI Server Test​

This test exercises the web interface to the CLI Server by placing a small CLI script in the cliserver/cli directory. It then calls that script via Apache at /cli/test.ctf and expects to get a matching time response. The test script is removed when the test is done. If the test fails, try it manually by adding the script to the look repository. Here is a sample script similar to the one the test program creates.

cgi header text/plain

message info OK

Make sure there is a running child process for the CLI Server from Apache. If it is not there, check the Apache error log to see why it did not start. Sometimes this is due to issues with your SELinux setup.

# ps -e f
[..snip..]
 1412 ?  Ss  0:00 /usr/sbin/httpd
 1426 ?  S   0:00  \_ /usr/sbin/httpd
 4840 ?  S   0:03  |   \_ /opt/collabnet/teamforge/add-ons/teamforge_cli/bin/ctf --mode fcgi

Make sure that your script was mirrored to the teamforge/var/cliserver/cli tree. If it was not, recheck the status of the mirror as in the previous test.

Because Apache manages the CLI Server, the Apache error log, or ssl_error.log, is the main place to look for issues.

CLI Cron Test​

In this test, a CLI script is placed in the cli/cron/once directory and then triggered by issuing a command to the CLI Server cron daemon via the SOAP API. The test job is expected to create a file in the cliserver/tmp directory. If the job fails to fire within a couple of minutes, the test fails. Look at the cli-cron.log to see whether there were any issues with the execution of the job.

/opt/collabnet/teamforge/log/cliServer/cli-cron.log

CLI Event Test​

In this last test, a CLI event hook script is created to catch the creation of a task group. The script is placed in the following CLI Server directory.

cli/events/postcommit/taskgroup/all

The test program then creates a new task group in the look project. The event handler is expected to create a file in the cliserver/tmp directory. If the file does not appear, the test fails. In that event, check the app/ctfevent.log file to determine whether the event fired. If it did but encountered an error, that error appears in the Apache error log.