# 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.
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
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.
On Linux, please ensure that both
docker-compose are on your
PATH and can be run from your command line.
You must run all
docker-compose commands as
Either by using a
root shell or by prefixing the commands with
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 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 (opens new window) at
Teamscale will automatically pick up the license when started.
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
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:6.3.2' restart: always working_dir: /var/teamscale volumes: - /var/teamscale:/var/teamscale - /var/teamscale/backup:/backup ports: - "8080:8080"
/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.
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.
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
cd /var/teamscale docker-compose down
# Customizing Configuration Files
Certain Teamscale settings are configured in configuration files that are stored inside the container in
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:/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
In this example, we set the timezone to
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 - /var/teamscale/backup:/backup ports: - "8080:8080"
You can then run the
date command from above again to ensure that the setting has been applied successfully.