# 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
|HTTP server port|
|Prefix of URLs|
|Bind address of the HTTP server|
|Database directory where all data is stored|
|The cache size used by the database in MB|
|The number of concurrent analysis worker jobs. |
When working with multiple projects, this can be used to parallelize analyses.
|Log level for logging service calls - one of |
|Whether to log the user of service calls|
|This is an expert setting and should not be changed. |
Valid options are:
|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|
# 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):
The directory specified in the Java system property
teamscale.license.path(if it is set)
The config directory in the Teamscale installation directory (given by TEAMSCALE_HOME environment variable; this variable is set automatically, if using the start script)
The current working directory
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
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
.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:
In a Windows environment please use the corresponding
.bat file in the same directory.
By default, Teamscale uses the configuration file
. 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
Check if Teamscale has started successfully by opening
in a web browser.
Default Admin Credentials
You can log in using the default credentials:
Teamscale writes a log-file named
teamscale.log in the execution
# 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
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
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.
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,