Teamscale Documentation

# How to install Teamscale with Docker and docker-compose

This guide shows you how to install and run Teamscale with Docker and docker-compose on either Windows or Linux. In this How-To we'll use /var/teamscale/ as the process working directory of Teamscale. You can substitute this path with a local path of your choice.

This How-To uses the Teamscale version 7.7.0. Please substitute this with your desired Teamscale version, e.g. the latest one. You can find a list of all available tags on Docker Hub (opens new window). Please note that we do not provide a latest tag.

# Prerequisites

To run Teamscale with Docker, you must install Docker (opens new window) and docker-compose (opens new window). On Windows, docker-compose is included in the Docker installation.

Minimal Version

Since Teamscale 8.3.0 at least version 20.10.10 of Docker is required. Run docker version to check the installed version.

On Linux, please ensure that both docker and docker-compose are on your PATH and can be run from your command line. You must run all docker and docker-compose commands as root. Either by using a root shell or by prefixing the commands with sudo.

Run docker version and verify that no errors are printed on the command line.

Use WSL 2 under Windows for Better Performance

When using Docker on Windows, running Docker from the Windows CLI has worse performance (opens new window) than running it from within the Windows Subsystem for Linux 2. Within WSL 2, mounting folders from the Windows host's file system, e.g. /mnt/c/, also has worse performance than mounting a WSL 2 path. Thus, we recommend that you run Docker from within your WSL 2 Linux distribution of choice and store all Teamscale-related files inside the WSL Linux.

# Prepare the Necessary Directories

Please create the following directory on the host machine (asuming you mount /var/teamscale as working_dir):

  • /var/teamscale/config - all configuration files for running Teamscale with Docker will be placed in this directory

The following directories are automatically created by Teamscale (asuming you mount /var/teamscale as working_dir):

  • /var/teamscale/logs - contains Teamscale's log files
  • /var/teamscale/storage - contains Teamscale's database
  • /var/teamscale/repo - contains remote clones of Git (or SAP) repositories
  • /var/teamscale/backup - contains Teamscale's backup zip files if you enable automatic backups in the web interface

On Linux, these directories must be readable and writable on the host system by the user with ID 1000 of the host system. If you are unsure, you can run sudo chown -R 1000 /var/teamscale to make that user the owner of those directories.

# Install your License File

Please place your license file (opens new window) at /var/teamscale/config/teamscale.license. Teamscale will automatically pick up the license when started.

# Prepare docker-compose

docker-compose is a command that lets you describe, start and stop a Docker container with a simple configuration file.

Please create a file called /var/teamscale/docker-compose.yaml. This file will define how to launch the Teamscale Docker container and how to map your local directories into the file system of the container.

Please substitute the Teamscale version and host file system path you would like to use in the lines marked below.





 


 
 
 
 








version: '3'

services:
  teamscale:
    image: 'cqse/teamscale:7.7.0'
    restart: always
    working_dir: /var/teamscale
    volumes:
      - /var/teamscale:/var/teamscale
    ports:
      - "8080:8080"
    environment:
      # The Teamscale memory limit (alternative to storing it in jvm.properties)
      TEAMSCALE_MEMORY: 4G
      # Overwrite settings from config/teamscale.properties
      TS_PROPERTIES: |-
        engine.workers=2
        instance.name=v7.7

Adjust the /var/teamscale paths in volumes before the colons and change the Teamscale version if necessary.

Note that the Teamscale installation resides at /opt/teamscale inside the container. By specifying the working_dir, we tell Teamscale to look for the configuration files in a different folder, i.e. /var/teamscale. This makes mounting all required config files easier.

Indentation is Significant in YAML

Please ensure that the whitespace at the beginning of each line is preserved correctly. Indentation in YAML files is significant and incorrect indentation will result in errors when running the container. You can only use spaces for indentation, not tabs.

# Starting the Docker Container

On Windows, you must first start the Docker Desktop app.

Please cd to the folder that contains the docker-compose.yml file and start Teamscale:

cd /var/teamscale
docker-compose up -d

Teamscale will be reachable under http://localhost:8080 (opens new window).

# Stopping the Docker Container

Run:

cd /var/teamscale
docker-compose down

# Customizing Configuration Files

Certain Teamscale settings are configured in configuration files that are stored inside the container in /opt/teamscale/config. To obtain a copy of the default files, you can run the following command.

Please substitute the Teamscale version you are using in your docker-compose.yml in the commands below.

docker run --rm -d --name ts_tmp cqse/teamscale:7.7.0 # launches the docker image
docker cp ts_tmp:/opt/teamscale/config /var/teamscale # copies the configuration files to your local disk
docker stop ts_tmp # stops the docker container

You can now edit the configuration files stored at /var/teamscale/config as desired. Consult the Administration of a Teamscale Installation reference for details on all available customization options.

# Changing the Time Zone

Once you have set up your docker container, it will likely be running in the UTC (Coordinated Universal Time) time zone. To verify this, you can run the following command that will print the container's current time:

docker exec -it <YourContainerId> date

If you want to change this setting to match the time zone of the host system, you can set the TZ environment variable in your docker-compose.yml file. In this example, we set the timezone to Europe/Berlin:








 
 





version: '3'

services:
  teamscale:
    image: 'cqse/teamscale:6.3.2'
    restart: always
    working_dir: /var/teamscale
    environment:
      TZ: "Europe/Berlin"
    volumes:
      - /var/teamscale:/var/teamscale
    ports:
      - "8080:8080"

You can then run the date command from above again to ensure that the setting has been applied successfully.

← Installing as Linux Service →