site-options.conf

TeamForge is controlled by settings in a master configuration file called site-options.conf. Some of the most useful configuration settings you can specify in the site-options.conf file are described here.

The site-options.conf file resides in the /opt/collabnet/teamforge/etc/ directory.

When TeamForge starts, it reads and implements the instructions provided as values to the variables in this file.

The basic procedure for configuring your TeamForge site, then, is to edit the site-options.conf file, supply a valid value for the token of interest, save the file, and rebuild the TeamForge runtime environment.

site-options.conf changes in TeamForge 17.1

TeamForge 17.1 includes major changes to site-options.conf configuration. The syntax for writing the HOST and DOMAIN tokens and the names of certain services have been changed in TeamForge 17.1. This section walks you through the list of changes and what it takes to build your TeamForge 17.1 site's master configuration file.

List of services and their identifiers

The following table lists the names of, both old (TeamForge 16.10 and earlier) and new (TeamForge 17.1 and later), TeamForge services. The ctfcore service, including its dependent services such as search, mail, ctfcore-database and codesearch, are mandatory services. You can have all mandatory services run on a single server or distribute them across several servers. All other services such as etl and subversion are optional. However, if you install an optional component, for example etl, it is mandatory to install services such as ctfcore-datamart too, which is required by etl.
Note: To ensure backward compatibility, TeamForge 17.1 supports both old and new syntaxes for defining your HOST and DOMAIN tokens. Similarly, TeamForge 17.1 supports both old and new service names. However, going forward, it is recommended to adjust your site-options.conf in line with these changes as support for older syntax and naming convention would be dropped in due course.
Service Also requires (either on the same or separate server) Mandatory/Optional Old name Description
ctfcore   Mandatory app Main TeamForge application server
search Mandatory indexer Indexing and searching
mail Mandatory NA (added in TeamForge 17.1) Email server
ctfcore-database Mandatory database Operational database
codesearch Mandatory codesearch Code search
etl   Optional etl ETL for datamart
ctfcore-datamart Mandatory if you have etl installed datamart Datamart database
subversion   Optional subversion SVN version control
cvs   Optional cvs CVS version control
gerrit   Optional gerrit Git/Gerrit version control
gerrit-database Mandatory if you have Git/Gerrit installed NA (added in TeamForge 17.1) Database for Git/Gerrit. In a distributed setup, add this identifier on the server where you want to run Gerrit database.
binary   Optional binary Artifact repository integration
binary-database Mandatory if you have binary installed NA (added in TeamForge 17.1) Database for artifact repository integration. Binary app (binary) and database (binary-database) have to be installed on the same server.
reviewboard   Optional reviewboard Review Board code review tool
reviewboard-database Mandatory if you have Review Board installed NA (added in TeamForge 17.1) Database for Review Board. In a distributed setup, add this identifier on the server where you want to run Review Board database.

SERVICES and PUBLIC_FQDN site-options.conf tokens

Syntax to define the services running on a TeamForge host

The syntax for defining the services running on a TeamForge host is:
  • <hostname>:SERVICES = list of services separated by space

Where <hostname> can be "localhost" or the server name as returned by the hostname command on the console. The latter is recommended as this allows reuse of the same site-options.conf file across all servers in a distributed setup. Here are some examples:

Example 1: Default single-server setup
  • localhost:SERVICES = ctfcore ctfcore-database ctfcore-datamart etl mail search codesearch subversion
Example 2: Single-server setup with Git integration
  • localhost:SERVICES = ctfcore ctfcore-database ctfcore-datamart etl mail search codesearch subversion gerrit gerrit-database
Example 3: Single-server setup with Review Board integration
  • localhost:SERVICES = ctfcore ctfcore-database ctfcore-datamart etl mail search codesearch subversion reviewboard reviewboard-database
Example 4: Three-server setup with Git and Binary integration
  • server01:SERVICES = ctfcore etl mail search codesearch binary
  • server02:SERVICES = subversion gerrit
  • server03:SERVICES = ctfcore-database ctfcore-datamart gerrit-database

Syntax to define the domain names for a TeamForge site

Assign a public FQDN (optional, but strongly recommended). Make sure there is a DNS A or CNAME record for this FQDN.

server01:PUBLIC_FQDN = teamforge.example.com
server02:PUBLIC_FQDN = scm.example.com

Service-specific FQDNs

Installing TeamForge with service-specific FQDNs (instead of machine-specific host/domain names) is highly recommended so that you will be able to change the system landscape at a later point in time without having any impact on the URLs (in other words, end users do not have to notice or change anything). For example, you can create FQDNs specifically for services such as Subversion, Git, mail, Codesearch and so on.

  • All such service-specific FQDNs must be long to a single sub domain and it is recommended to create a new sub domain for TeamForge.
  • A wildcard SSL cert is required if you are using service-specific FQDNs. SNI SSL cert cannot be used.
  • When SSL is enabled and no custom SSL-certificates are provided, a self-signed wildcard cert is generated for the sub domain.
  • When SSL is enabled and a custom SSL-certificate is provided, the CN of the certificate is verified to be a wildcard CN.
The following configuration shows the list of services and FQDNs for specific services such as ctfcore, subversion, gerrit and mail in a single server TeamForge installation:
localhost:SERVICES = ctfcore ctfcore-database ctfcore-datamart etl mail search codesearch subversion
localhost:PUBLIC_FQDN = app.forge.collab.net
localhost:ctfcore:PUBLIC_FQDN = ctf.forge.collab.net
localhost:subversion:PUBLIC_FQDN = svn.forge.collab.net
localhost:gerrit:PUBLIC_FQDN = git.forge.collab.net
localhost:mail:PUBLIC_FQDN = mail.forge.collab.net

In a single server setup, all these domain names point to a single server. However, when services are later distributed across multiple servers, all it takes to avoid an end user impact is to adjust these domain names to point to different servers.