# Administration of a Teamscale Installation
This article gives a detailed reference of the configuration options of a Teamscale installation. It assumes that the basic installation of Teamscale is completed and Teamscale can be accessed via the web interface.
# Configuring Teamscale
The Teamscale installation can be adjusted to the host environment with configuration files, environment variables or JVM arguments.
Most configuration files are already shipped with the Teamscale installation in the
If not explicitly specified, this is the only location for loading configuration files.
Otherwise, configuration files are always loaded in the following order by Teamscale:
Dedicated Configuration Directory: If the environment variable
TEAMSCALE_CONFIGis set, the folder which the variable points to is the primary location for loading configuration files. The default installation does not specify this variable.
Working Directory: A folder named
configwithin the working directory of the Teamscale process. The working directory is the directory Teamscale is started from and equals the installation directory if not configured differently. See Separate Working Data from Installation Files for more information.
Installation Directory: A folder named
configwithin the installation directory. The installation directory is determined by the environment variable
TEAMSCALE_HOME. This variable is set by startup scripts.
This yields the following resolution order:
As soon a configuration file is found, other directories are no longer scanned.
# Primary Settings – teamscale.properties
teamscale.properties file contains the most central configuration options for running Teamscale,
e.g., specifying the amount of workers or where data is stored.
The file can be provided in any of the configuration directories.
Loading of a specific config file can be forced with startup argument
In addition properties can be provided with the environment variable
TS_PROPERTIES and overwrite those in the configuration file.
The table below shows the options available in the
| || ||HTTP server port|
| ||Prefix of URLs|
| ||Bind address of the HTTP server|
| || ||Database directory where all data is stored, relative to the working directory.|
| || ||This is an expert setting and should not be changed. |
Valid options are:
| || ||The cache size used by the database in MB|
| || ||The number of concurrent analysis worker jobs. |
See Configuring Workers for details.
| || ||Log level for logging service calls - one of |
| || ||Whether to log the user of service calls|
| ||Port to be used for HTTPS. |
If this option is not set, HTTPS is disabled. See this guide to enable HTTPS.
| ||The absolute path to the Java keystore containing the certificate and private key|
| ||The password for the keystore|
| ||The alias of the certificate and private key in the keystore|
| || ||The directory where custom check JARs can be deployed. |
A relative path will be resolved to the working directory first and if not found to the installation directory.
To operate RocksDB on a Windows environment, please be aware that you also need to install the Visual C++ Redistributable for Visual Studio 2015.
# Configuring the Webserver
In the default configuration, Teamscale starts a web server on your
machine, using port
8080, accessible via
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
# Configuring Workers
When working with multiple projects,
engine.workers 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.
# JVM Settings – jvm.properties
The config file
jvm.properties contains variables that are loaded before the JVM starts.
Please be aware that this file is no regular shell or batch script.
Multiline variables with
\ escaping and environment variable expansion will not work.
# JVM Memory
By default, the Teamscale start script will launch a JVM with a maximum Java heap size of 2.500mb.
You can change this by adjusting
Alternatively, you can set the environment variable
TEAMSCALE_MEMORY which takes precedence over the value specified in
Dealing with Memory Problems
If Teamscale runs into memory-related problems , please refer to this how-to page.
# JVM Arguments
Additional flags (e.g,
-Dmy.flag=value) that should be passed to the JVM can be specified using the
In addition, you can specify flags using the regular environment variable
The value of
TEAMSCALE_VM_ARGS is passed to the JVM before the values of
The JVM is always started with flags
# License – teamscale.license
Teamscale needs a valid license to run. Teamscale automatically searches several locations for a valid Teamscale license (in this order):
- The content of the environment variable
TS_LICENSE. The following example shows how to copy the content of a license file into the environment variable when starting Teamscale with the shell script.
TS_LICENSE=$(cat ~/custom_folder/teamscale.license) export TS_LICENSE ./teamscale.sh
A file named
teamscale.licensein any of the configuration directories
A file named
teamscale.licensein the home directory of the user running Teamscale
You need to ensure that a valid license exists in one of these locations before starting Teamscale.
# Logging – log4j2.yaml
Teamscale writes a log-file named
logs/teamscale.log in the working directory.
To configure Teamscale's logging settings, you can do so in the file
log4j2.yaml in one of the configuration directories.
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.
Legacy Log4j 1 configuration file
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.
Teamscale will refuse to start if the old configuration file is found.
# Encryption – teamscale.key
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
teamscale.key in one of the
config directories. 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
.key. When reading a backup, Teamscale will automatically
find the correct key to use.
# Stylesheet – custom.css
The Teamscale installation can be customized with a separate stylesheet by creating a file
custom.css in one of the configuration directories with CSS rules.
# Separate Working Data from Installation Files
The working directory is used to resolve configuration files and relative directories specified in configuration files, e.g., the directory for data storage, custom checks or log files. If not explicitly configured the working directory of Teamscale is identical to the Teamscale installation directory.
For a simpler update process of Teamscale you may prefer separating files provided by the Teamscale installation from manually edited configuration files and data calculated during analysis. This way you can simply replace the whole installation directory on an update, which may reduce manual effort if Teamscale is installed as Windows or Linux service.
Changing the working directory depends on the used way of installing Teamscale on the host environment:
- Plain Docker: Specify
-wwhen starting the container. The provided path should be mapped to the host or a volume.
- Docker Compose: Specify the
working_dirkey for the Teamscale service in your
docker-compose.yml. The provided path should be mapped to the host or a volume.
- Windows service: Specify
- Linux systemd service: Specify
- Stock startup script: When using
cdto the directory you want to be the working directory and start Teamscale by specifying the path to the startup script, e.g.,
Please be aware that changing the working directory after initial analysis may cause already calculated data to no longer be available in Teamscale as the storage directory will most likely be resolved to another location. You can, however, simply copy the existing storage directory to the new working directory location.
# 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.
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 with a JVM argument. E.g., to enforce a session timeout of 8 hours, add: