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
etl	`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	`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	`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	`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.