TeamForge script

Use the teamforge script to deploy and undeploy services, start and stop services, verify the status of services, verify the application environment, bootstrap or migrate data and do much more.

Overview

Use the teamforge script wherever applicable as it subsumes the functions of the following legacy TeamForge scripts:
  • bootstrap-data.sh
  • bootstrap-data.py
  • bootstrap-reporting-data.sh
  • bootstrap-reporting-data.py
  • create-runtime.py
  • collabnet
  • migrate.py
Run teamforge script as follows:
  • /opt/collabnet/teamforge/bin/teamforge [command] [-s serviceName] [parameter]

For example, the following command displays the status of all the services:

TeamForge components and services

Components
TeamForge comprises of a set of components such as ctfcore, subversion, james, and so on. Some components are always required to be installed, while others are optional. By spreading these components over multiple RPMs, we make sure that users do not have to install everything all the time. Though this is valuable, RPMs alone prove insufficient to manage the components and their inter-dependencies.
  • Some components do not have a physical representation but are configuration-only.
  • RPM dependencies are restricted to the local machine only; however, in a distributed installation, dependencies between components must be tracked across servers.
In addition to the physical componentization (using RPMs), there is also a need for a logical componentization of TeamForge.
Services
Services represent a logical component of TeamForge. Such a logical component may either be a feature, which the user explicitly opts to install (for example, CVS) or a technical component (for example, Apache and Logrotate), which other services depend on. Services come with additional metadata which makes it possible to track and manage dependencies to a more fine-grained level.
  • Deployment dependencies specify which other services need to be deployed locally.
  • Provided Endpoints specify which network endpoints the service offers.
  • Required Endpoints specify which network endpoints the service depends on.
As such services are more fine-grained than RPMs and it is common to have a single RPM containing multiple services.
Service life cycle
A service can be in one of the following states:
  • Uninstalled: A service is uninstalled if the RPM that contains it is not installed. Uninstalled services do not exist as far as TeamForge is concerned.
  • Undeployed: The RPM containing the service is installed, but the service has not been deployed yet. Deployment is also referred to as "creating the runtime", but is specific to one service.
  • Dependencies unavailable: The service itself might be available, but at least one of its deployment dependencies is not in "Available" state.
  • Available: Service is fully functional.
Services that manage data have the following additional states:
  • Not bootstrapped: Data structures have not been initialized yet.
  • Not migrated: Data structures are initialized, but data needs to be migrated.
Services that have a daemon have the following additional states:
  • Dependencies unavailable: The service itself might be available, but at least one of its deployment dependencies is not in "Available" state.
  • Ports Blocked: The service is impeded from starting up because at least one of the ports it needs is in use by a different process.
  • Stopped: Service is an auto start-type service, yet is stopped.
  • Inactive: Service is a demand start-type service and is stopped.
  • Starting: Service is in the process of starting up.
  • Available: Service is running and healthy according to its health check.
  • Unhealthy: Service is running but unhealthy according to its health check.
  • Dead: Service is supposed to be running, but the process disappeared.
  • Doomed: Service is technically running, but it will never work properly because some part of it failed to initialize properly.
  • Stopping: Service is in the process of stopping.

Parameters

teamforge script accepts the following command line parameters:
[-s | --service]
Use the -s parameter to selectively start, stop, and bootstrap a specific service or component. For example, the following command gets you the status of Jboss:
  • /opt/collabnet/teamforge/bin/teamforge status -s jboss
[-f | --site_options_file]
Use the -f parameter to pass the site-options.conf file's path as a command line parameter (default is /opt/collabnet/teamforge/etc/site-options.conf).
[--skip-verification]
Pass this parameter if you want to skip environment verification.
[-y | --yes]
Pass this parameter if you want to skip confirmation prompts.

Commands

teamforge script can perform the following actions:
status
Show status of all services. Use the -s parameter to know the status of a specific service.
bootstrap
Bootstrap data (re-create data structures). Use the -s parameter to selectively bootstrap a specific component. Suppose, you did not have SVN on your TeamForge site and if you add SVN while upgrading to TeamForge 16.10. You can now selectively bootstrap SVN alone.
deploy
Deploy service(s).
migrate
Migrate data to latest schema.
provision
Provision/reprovision machine. The "provision" command performs tasks such as creating the runtime, starting and stopping services, bootstrapping (fresh install) or migrating (upgrade) data, initializing services and so on.

If you have SELinux in "enforcing" mode, you must either disable SELinux or switch to "Permissive" mode (recommended) before running the /opt/collabnet/teamforge/bin/teamforge provision command. TeamForge create runtime fails otherwise.

Important: If you have SELinux in "enforcing" mode, you must either disable SELinux or switch to "Permissive" mode (recommended) before running the /opt/collabnet/teamforge/bin/teamforge provision command. TeamForge create runtime fails otherwise.
undeploy
Undeploy service(s).
start
Start service(s).
stop
Stop service(s).
verify
Verify environment.
show-endpoints
Show endpoints
show-dependencies
Show deployment dependencies
reinitialize
Reinitializes all the TeamForge services
snapshot
Dumps relevant diagnostic information to the console (stdout) for each deployed service.

Troubleshooting

Deploy error while upgrading TeamForge
The following error message might show up when you run the /opt/collabnet/teamforge/bin/teamforge provision command during TeamForge upgrades.

/opt/collabnet/teamforge/service/legacy-runtime/hooks/runtime-option-defaults/tomcat/00-scm-server-check.py failed: No module named constants

This happens if the runtime folder is not found in /opt/collabnet/teamforge/. In such cases, run the following command:
  • find /opt/collabnet/teamforge/dist/lib/multiplatform/python/ -name *.pyc -exec rm -f {} +

Logging

teamforge script writes entries to /opt/collabnet/teamforge/log/runtime/runtime.log file.

Parent topic: Scripts installed with TeamForge