# 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.