# Administration of a Teamscale Installation

This article gives a detailed reference of the installation options when configuring Teamscale. For the remainder of this article, <Teamscale-Dir> is the absolute path to this directory.

# Configuring Teamscale

The table below shows the configuration options. To operate RocksDB (the default database) on a Windows environment, please be aware that you also need to install the Visual C++ Redistributable for Visual Studio 2015.

# Basic Configuration Settings

Option Description Default
server.portHTTP server port8080
server.urlprefixPrefix of URLs
server.bind-hostnameBind address of the HTTP server
database.directoryDatabase directory where all data is stored<teamscale-Dir>/storage
database.cache-sizeThe cache size used by the database in MB512
engine.workersThe number of concurrent analysis worker jobs.
When working with multiple projects, this can be used to parallelize analyses.
  • Increasing this value requires the JVM memory settings to be adapted as well.
  • Allocate about 2GB per worker. For best performance use as many workers as cpu cores are available.
  • On larger instances, use one less worker so one core remains free for handling service requests during high-load situations.
2
servicelog.loglevelLog level for logging service calls - one of OFF, INFO, WARN, ERRORWARN
servicelog.loguserWhether to log the user of service callsfalse
database.typeThis is an expert setting and should not be changed.
Valid options are: leveldb, rocksdb and cassandra
rocksdb
https.portPort to be used for HTTPS.
If this option is not set, HTTPS is disabled. See this guide to enable HTTPS
https.keystore-pathThe absolute path to the Java keystore containing the certificate and private key
https.keystore-passwordThe password for the keystore
https.certificate-aliasThe alias of the certificate and private key in the keystore

# Ways to Provide a Teamscale License

Teamscale needs a valid license to run. Teamscale automatically searches several locations for a license file named teamscale.license (in this order):

  1. The directory specified in the Java system property teamscale.license.path (if it is set)

  2. The config directory in the Teamscale installation directory (given by TEAMSCALE_HOME environment variable; this variable is set automatically, if using the start script)

  3. The current working directory

  4. The home directory of the user running Teamscale

Before starting Teamscale for the first time, it has to be ensured that a valid license exists in one of these locations.

# Configuring Encryption

Teamscale encrypts all tables in the storage system that might contain sensitive information, such as passwords to your SVN server. The encryption algorithm used is AES-256. By default, Teamscale uses a default key that is hard-coded. To further improve security, you can provide your own key. For this, write your key or passphrase into the file teamscale.key in the config directory. Teamscale then uses the content of this file for initializing the key that is used to protect your data. The file should be protected using the usual file-system permissions.

When creating backups, you can select to use this local key instead of Teamscale's default key for encrypting the backup. The benefit of this method is that nobody without your key file can read the encrypted parts of the backup. On the flip-side, you can not import this backup into an instance that does not know the secret key of the instance. To import into an instance that uses a different encryption key, you either have to use a backup that uses Teamscale's key instead of the local key, or you must provide the key as alternative decryption key. For this, place the key into the config directory using any file name with the extension .key. When reading a backup, Teamscale will automatically find the correct key to use.

# Manually Starting Teamscale

As a prerequisite for starting Teamscale it has to be ensured that the Java executable is on the path. Teamscale can be started with Teamscale startup shell script by executing following command:

<Teamscale-Dir>/teamscale.sh

In a Windows environment please use the corresponding .bat file in the same directory.

By default, Teamscale uses the configuration file <Teamscale-Dir>/config/teamscale.properties . To provide a different configuration file, use the -c option of the start script:

<Teamscale-Dir>/teamscale.sh -c <path-to-teamscale-config.properties>

In the default configuration, Teamscale starts a web server on your machine, using port 8080. This web server will be also available from other machines in your network. If you do not want this, remove the comment before the line server.bind-hostname=localhost in the file teamscale.properties .

Check if Teamscale has started successfully by opening

http://localhost:8080

in a web browser.

Default Admin Credentials

You can log in using the default credentials:

  • User: admin
  • Password: admin

Teamscale writes a log-file named teamscale.log in the execution directory.

# Logging Settings

To configure Teamscale's logging settings, you can do so in the file config/log4j2.yaml. This is a Log4j 2 configuration file in the YAML format, which you can adjust according to the guidelines available at the official documentation page. If you need to override the file location for some reason, you can set the Java system property log4j.configurationFile to point to the desired path. Alternatively, the environment variable TS_LOGGING_CONF may hold the content of a properties file as documented here.

Prior to the Teamscale release version 4.8, the given properties had to use the naming required by Log4j 1. Starting with Teamscale 4.8, the Log4j 2 property names are used instead. Please note that the new configuration format is not backwards-compatible.

# JVM Memory Settings

By default, the Teamscale start script will launch a JVM with a maximum Java heap size of 2.500mb. You can change this by setting the environment variable TEAMSCALE_MEMORY or adjusting the file config/jvm.properties.

Dealing with Memory Problems

If Teamscale runs into memory-related problems , please refer to this how-to page.

# Usage Data Reporting (optional)

You can help us to improve Teamscale by activating Usage Data Reporting in the Admin settings. This option will regularly transfer information about the used features and statistics about errors to our servers. You can configure, which information you are willing to share and also see a preview of the shared information. The preview dialog also contains a link to a web form that allows a one-time usage data reporting by copying the displayed preview information there. Please note that the automatic reporting needs out-bound HTTPS connection to our own servers.

Usage Reporting

Teamscale will only report generic information, but never sensitive information such as code or user data.

# Configuring Session Timeout

By default, a user that logs into Teamscale obtains a session that lasts 48 hours. This allows users to stay logged in as long as they are active every day - even in case of time zone changes. If you prefer to have a different session timeout, you can configure it in the JVM_EXTRA_ARGS entry in config/jvm.properties. e.g., to enforce a session timeout of 8 hours, add:

-Dcom.teamscale.session-timeout=8