# Installing Teamscale with Docker

This guide shows you how to install and run Teamscale with Docker and docker-compose on either Windows or Linux.

All configuration files for running Teamscale with Docker will be placed in the same directory. In this How-To we'll use /var/teamscale/, but you can substitute this path with a local path of your choice.

This How-To uses the Teamscale version 6.3.2. 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. Please note that we do not provide a latest tag.

# Prerequisites

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

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 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 directories:

  • /var/teamscale/storage - contains Teamscale's database
  • /var/teamscale/logs - contains Teamscale's log files
  • /var/teamscale/config - contains all configuration files
  • /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 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'

    image: 'cqse/teamscale:6.3.2'
    restart: always
    working_dir: /var/teamscale
      - /var/teamscale:/var/teamscale
      - /var/teamscale/backup:/backup
      - "8080:8080"

Adjust the /var/teamscale paths and change the Teamscale version if necessary.

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.

# Stopping the Docker Container


cd /var/teamscale
docker-compose down

# Customizing Configuration Files

Certain Teamscale settings are configured in configuration files that are stored in /var/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:6.3.2 # launches the docker image
docker cp ts_tmp:/var/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.