Docker install

Tag latest

The latest tag in Docker Hub refers to the most advanced version, not to the most recently pushed release image. Development tags such as nightly, IT (Integration Testing), and RC (Release Candidate) are not considered.

For example, consider the scenario where the image versions are pushed to Docker Hub in the following order: 8.0.0, 7.5.2, 8.1.0.RC1, and nightly.
In this case, the latest tag will point to version 8.0.0.

Following Docker best practices, it is recommended to avoid using the latest tag and instead specify explicit version numbers.

Quick Start

To quickly play with SquashTM:

Install Docker if it is not already present on your computer.

Create a docker-compose.yml file with this content:

services:
  squash-tm-pg:
    container_name: squash-tm-pg
    environment:
      POSTGRES_DB: squashtm
      POSTGRES_USER: squashtm
      POSTGRES_PASSWORD: MustB3Ch4ng3d
    image: postgres:17
    ports:
      - 5432:5432

  squash-tm:
    image: squashtest/squash:12.0.2
    depends_on:
      - squash-tm-pg
    environment:
      SPRING_PROFILES_ACTIVE: postgresql
      SPRING_DATASOURCE_URL: jdbc:postgresql://squash-tm-pg:5432/squashtm
      SPRING_DATASOURCE_USERNAME: squashtm
      SPRING_DATASOURCE_PASSWORD: MustB3Ch4ng3d
    ports:
      - 8090:8080/tcp
    volumes:
      - squash-tm-logs:/opt/squash-tm/logs

volumes:
  squash-tm-logs:

Execute the command docker compose up.
Log in http://localhost:8090/squash using login "admin" and password "admin".

Configuring

SquashTM is a Spring Boot application, it can be configured using environment variables as explained here.

Environment variables

Database access

The database connection is configured based on the first matching environment variable found in the following order of priority:

Shell environment variables defined in the container: SPRING_PROFILES_ACTIVE or SPRING_DATASOURCE_*
Shell environment variables defined in the container: SQTM_DB_*
Configuration file: squash.tm.cfg.properties file (located in the config directory)
Internal default settings

Spring variables

Environment variables	Corresponding Spring parameter
SPRING_PROFILES_ACTIVE	`spring.profiles.active`
SPRING_DATASOURCE_URL	`spring.datasource.url`
SPRING_DATASOURCE_USERNAME	`spring.datasource.username`
SPRING_DATASOURCE_PASSWORD	`spring.datasource.password`

These settings are described here.

SQTM_DB_* variables

Variable	Description	MariaDB Default	PostgreSQL Default
SQTM_DB_TYPE	Either `mariadb` or `postgresql`	(special)	(special)
SQTM_DB_HOST	Hostname of the database server	`mariadb`	`postgres`
SQTM_DB_PORT	Port of the database sever	`3306`	`5432`
SQTM_DB_NAME	The name of the database	`squashtm`	`squashtm`
SQTM_DB_SCHEMA	The name of the schema	`$DB_NAME`	`public`
SQTM_DB_USERNAME	The username for SquashTM	`root`	`postgres`
SQTM_DB_PASSWORD	The password for SquashTM	(none)	(none)

Notes:

(none): the variable is mandatory and has no default value;
(special): see below;

Variable `SQTM_DB_TYPE`

SQTM_DB_TYPE has an impact on the default values for several others variables. The best practice is to define it explicitly.
Be careful to type in the intended value correctly (e.g. postgresql and not postgres), otherwise it will not start.

Other useful variables

Timezone

You can adjust your container's timezone settings with the TZ environment variable.

For example to set your timezone to GMT +2, add the following parameter to the docker run command:

--env TZ=Europe/Paris

App config using `JAVA_TOOL_OPTIONS`

The JAVA_TOOL_OPTIONS environment variable is used to pass arguments to a Java application, without modifying the application's startup script or command line.

There are a few caveats, however. It cannot be used yet to configure the heap size (other JVM flags work fine).
Another shortcoming is that it cannot be supplemented; only redeclared. The Dockerfile sets its default to -Djava.awt.headless=true, which is required because SquashTM runs in a non-GUI Linux environment. If you need to override it, please remember to manually add this parameter back (otherwise you may experience troubles when generating and exporting reports).
These inconveniences originate from archaisms in the startup script and will be addressed in future releases.

Example to run SquashTM with the Fiji timezone and enable all Spring Boot actuator endpoints (use with caution, this will expose sensitive settings!):

export SQTM_OPTS="-Djava.awt.headless=true \
                  -Duser.timezone=Pacific/Fiji \
                  -Dmanagement.endpoints.access.default=unrestricted \
                  -Dmanagement.endpoints.web.exposure.include=*"

docker run --rm -d -p 8090:8080 -e JAVA_TOOL_OPTIONS="$SQTM_OPTS" squashtest/squash:12.0.2

App config using `SPRING_APPLICATION_JSON`

As explained here, SPRING_APPLICATION_JSON is an environment variable in Spring Boot that allows you to define application configuration properties as a JSON string.

Example to enable support for SSL offload:

cat << EOF > tmconf.json
{
    "server": {
        "use-forward-headers": true
    }
}
EOF

docker run --rm -d -p 8090:8080 -e SPRING_APPLICATION_JSON="$(jq -c . < tmconf.json)" squashtest/squash:12.0.2

Deploying SquashTM

The following sections show how to deploy SquashTM using an external PostgreSQL DB container or an external MariaDB container. Examples of YAML files also show how to deploy this solution using Docker Compose or Kubernetes.

With PostgreSQL

The database is created by the database container and automatically populated by the application container on first run, or upgraded as necessary when a newer version of SquashTM is deployed.

All data from the database will be saved within the local volume named squash-tm-db-pg. So the db container (called squash-tm-pg) can be stopped and restarted with no risk of losing them.

Spring variablesSQTM_DB_* variables

docker network create squash-tm-postgresql

docker run -it -d --name='squash-tm-pg' \
--network squash-tm-postgresql \
-e POSTGRES_USER=squashtm \
-e POSTGRES_PASSWORD=MustB3Ch4ng3d \
-e POSTGRES_DB=squashtm \
-v squash-tm-db-pg:/var/lib/postgresql/data \
postgres:17

sleep 10

docker run -it -d --name=squash-tm \
--network squash-tm-postgresql \
-e SPRING_PROFILES_ACTIVE=postgresql \
-e SPRING_DATASOURCE_USERNAME=squashtm \
-e SPRING_DATASOURCE_PASSWORD=MustB3Ch4ng3d \
-e SPRING_DATASOURCE_URL=jdbc:postgresql://squash-tm-pg:5432/squashtm \
-v squash-tm-logs:/opt/squash-tm/logs \
# Uncomment below if you want to enable built-in plugins.
#-v your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg \
-p 8090:8080 \
squashtest/squash:12.0.2

docker network create squash-tm-postgresql

docker run -it -d --name='squash-tm-pg' \
--network squash-tm-postgresql \
-e POSTGRES_USER=squashtm \
-e POSTGRES_PASSWORD=MustB3Ch4ng3d \
-e POSTGRES_DB=squashtm \
-v squash-tm-db-pg:/var/lib/postgresql/data \
postgres:17

sleep 10

docker run -it -d --name=squash-tm \
--network squash-tm-postgresql \
-e SQTM_DB_TYPE=postgresql \
-e SQTM_DB_USERNAME=squashtm \
-e SQTM_DB_PASSWORD=MustB3Ch4ng3d \
-e SQTM_DB_NAME=squashtm \
-e SQTM_DB_HOST=squash-tm-pg \
-v squash-tm-logs:/opt/squash-tm/logs \
# Uncomment below if you want to enable built-in plugins.
#-v your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg \
-p 8090:8080 \
squashtest/squash:12.0.2

Wait 3-4 minutes, the time for SquashTM to initialize.
Then, log in to http://localhost:8090/squash (admin / admin)

If you have your own plugins, add -v squash-tm-plugins:/opt/squash-tm/plugins. (See here)

With MariaDB

Database is created by the database container and automatically populated by the application container on first run, or upgraded as necessary when a newer version of SquashTM is deployed.

All data from the database will be saved within the local volume named squash-tm-db-mdb. So the db container (called squash-tm-mdb) can be stopped and restarted with no risk of losing them.

Spring variablesSQTM_DB_* variables

docker create network squash-tm-mariadb

docker run -it -d --name='squash-tm-mdb' \
--network squash-tm-mariadb \
-e MARIADB_ROOT_PASSWORD=MustB3Ch4ng3d \
-e MARIADB_USER=squashtm \
-e MARIADB_PASSWORD=MustB3Ch4ng3d \
-e MARIADB_DATABASE=squashtm \
-v squash-tm-db-mdb:/var/lib/mysql \
mariadb:10.7 --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

sleep 10

docker run -it -d --name=squash-tm \
--network squash-tm-mariadb \
-e SPRING_PROFILES_ACTIVE=mariadb \
-e SPRING_DATASOURCE_USERNAME=squashtm \
-e SPRING_DATASOURCE_PASSWORD=MustB3Ch4ng3d \
-e SPRING_DATASOURCE_URL=jdbc:mariadb://squash-tm-mdb:3306/squashtm \
-v squash-tm-logs:/opt/squash-tm/logs \
# Uncomment below if you want to enable built-in plugins.
#-v your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg \
-p 8090:8080 \
squashtest/squash:12.0.2

docker create network squash-tm-mariadb

docker run -it -d --name='squash-tm-mdb' \
--network squash-tm-mariadb \
-e MARIADB_ROOT_PASSWORD=MustB3Ch4ng3d \
-e MARIADB_USER=squashtm \
-e MARIADB_PASSWORD=MustB3Ch4ng3d \
-e MARIADB_DATABASE=squashtm \
-v squash-tm-db-mdb:/var/lib/mysql \
mariadb:10.7 --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

sleep 10

docker run -it -d --name=squash-tm \
--network squash-tm-mariadb \
-e SQTM_DB_TYPE=mariadb \
-e SQTM_DB_USERNAME=squashtm \
-e SQTM_DB_PASSWORD=MustB3Ch4ng3d \
-e SQTM_DB_NAME=squashtm \
-e SQTM_DB_HOST=squash-tm-mdb \
-v squash-tm-logs:/opt/squash-tm/logs \
# Uncomment below if you want to enable built-in plugins.
#-v your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg \
-p 8090:8080 \
squashtest/squash:12.0.2

Wait several minutes while SquashTM initializes the database. Then, log in to http://localhost:8090/squash (admin / admin).

If you have your own plugins, add -v squash-tm-plugins:/opt/squash-tm/plugins. (See here)

Docker Compose

`docker-compose.yml` file

The following example of a docker-compose.yml links SquashTM to a MariaDB database. The environment variables should be set in a .env file (saved in the same repository as the docker-compose.yml).

Spring variablesSQTM_DB_* variables

services:
  squash-tm-md:
    image: mariadb:10.7
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_PASSWORD}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_DATABASE: ${DB_DATABASE}
    ports:
      - 3306:3306
    volumes:
      - "./init.sql:/docker-entrypoint-initdb.d/init.sql"
    # Uncomment for persistent data
    #  - "/path/to/local/data:/var/lib/mysql"


  squash-tm:
    image: squashtest/squash:12.0.2
    depends_on:
      - squash-tm-md
    environment:
      SPRING_PROFILES_ACTIVE: mariadb
      SPRING_DATASOURCE_URL: jdbc:mariadb://squash-tm-md:3306/${DB_DATABASE}
      SPRING_DATASOURCE_USERNAME: ${DB_USER}
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
    ports:
      - 8090:8080/tcp
    volumes:
      - squash-tm-logs:/opt/squash-tm/logs
    # Uncomment the line below if you want to enable the built-in plugins.
    #- your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg 

volumes:
  squash-tm-logs:

services:
  squash-tm-md:
    image: mariadb:10.7
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_PASSWORD}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_DATABASE: ${DB_DATABASE}
    ports:
      - 3306:3306
    volumes:
      - "./init.sql:/docker-entrypoint-initdb.d/init.sql"
    # Uncomment for persistent data
    #  - "/path/to/local/data:/var/lib/mysql"


  squash-tm:
    image: squashtest/squash:12.0.2
    depends_on:
      - squash-tm-md
    environment:
      SQTM_DB_TYPE: mariadb
      SQTM_DB_USERNAME: ${DB_USER}
      SQTM_DB_PASSWORD: ${DB_PASSWORD}
      SQTM_DB_NAME: ${DB_DATABASE}
      SQTM_DB_HOST: squash-tm-md
      SQTM_DB_PORT: "3306"
    ports:
      - 8090:8080/tcp
    volumes:
      - squash-tm-logs:/opt/squash-tm/logs
    # Uncomment the line below if you want to enable the built-in plugins.
    #- your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg 

volumes:
  squash-tm-logs:

`.env` file

DB_USER=squashtm
DB_PASSWORD=MustB3Ch4ng3d
DB_DATABASE=squashtm

`init.sql` file

The init.sql file must be placed at the root of the project when using a MariaDB database. This script grants the necessary privileges and roles to the squashtm user:

GRANT USAGE ON squashtm.* TO 'squashtm'@'%' WITH GRANT OPTION;
GRANT ALL ON squashtm.* TO 'squashtm'@'%';
CREATE ROLE alter_squash_table_seq;
GRANT alter_squash_table_seq TO 'squashtm'@'%';
SET DEFAULT ROLE alter_squash_table_seq FOR 'squashtm'@'%';
FLUSH PRIVILEGES;

If you have your own plugins, add -v squash-tm-plugins:/opt/squash-tm/plugins. (See here)

Run Docker Compose

Copy the docker-compose.yml that correspond to your need.
You will find several docker-compose repository on our GitLab:
Do not forget to create an .env file (or set the value of environment variables directly in the docker-compose.yml file);
In the docker-compose.yml directory, run docker compose up or docker compose up -d for daemon mode;
Log in to http://localhost:8090/squash or http://{host_ip}:8090/squash;

For more information about Docker Compose, here is the documentation.

Install SquashTM license

Instructions for installing SquashTM license is available here.

Using SquashTM container with a reverse proxy

Two examples of docker-compose.yml deploying SquashTM behind a reverse proxy are available on our GitLab:

These solutions use a docker image from jwilder based on nginx-proxy.

Here is an example of SquashTM deployed behind a reverse-proxy using PostgreSQL database:

services:
  squash-tm-pg:
    container_name: squash-tm-pg
    environment:
      POSTGRES_DB: ${DB_DATABASE}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USER}
    image: postgres:17
    ports:
      - 5432:5432
    # Uncomment bellow for persistent data
    # volumes:
    #   - "/path/to/local/data:/var/lib/postgresql/data"
    networks:
      - db-network

  squash-tm:
    depends_on:
      - squash-tm-pg
    environment:
      SQTM_DB_TYPE: postgresql
      SQTM_DB_USERNAME: ${DB_USER}
      SQTM_DB_PASSWORD: ${DB_PASSWORD}
      SQTM_DB_NAME: ${DB_DATABASE}
      VIRTUAL_HOST: mysquash.example.com
      SQTM_DB_PORT: "5432"
      SQTM_DB_HOST: squash-tm-pg
    ports:
      - 8090:8080/tcp
    image: squashtest/squash:12.0.2
    volumes:
      - squash-tm-logs:/opt/squash-tm/logs
      # Uncomment bellow if you want to activate plugins
      #- your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg
    networks:
      - nginx-proxy
      - db-network

  nginx-proxy:
    container_name: nginx
    image: jwilder/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
    networks:
      - nginx-proxy

volumes:
  squash-tm-logs:

networks:
  nginx-proxy:
  db-network:

And the .env file:

DB_USER=squashtm
DB_PASSWORD=MustB3Ch4ng3d
DB_DATABASE=squashtm

If you have your own plugins, add -v squash-tm-plugins:/opt/squash-tm/plugins. (See here)

Kubernetes

A Kubernetes manifest of SquashTM can be found here.

To do a quick install, you will need either a k8s cluster or a minikube (not suited for production).

1) Premium only: Create a secret from license file:

kubectl create secret generic squashtm-prod-license --from-file=licensefile=./squash-tm.lic

2) Optional: Activate plugins and configure SquashTM as configMap:

Modify the files start-plugins.cfg and squash.tm.cfg.properties accordingly to documentation:

start-plugins.cfg defined as file here and the link to documentation here
squash.tm.cfg.properties defined as file here

Create the configmap:

kubectl create configmap config-squash-tm --from-file=./squash.tm.cfg.properties
kubectl create configmap config-plugin-tm --from-file=./start-plugins.cfg

3) Apply manifest: If you applied step 1 or 2, uncomment the linked configuration in the SquashTM's K8S manifest.

kubectl apply -f ./squash-mariadb.yaml # or postgresql

4) Access to SquashTM:

On minikube:

sudo minikube tunnel #Mandatory to access the local loadbalancer

You can access SquashTM with the address http://localhost:8080/squash.

On k8s:

kubectl get svc

Get the correct External IP.
You can access SquashTM with the address http://<EXTERNAL-IP\>:8080/squash.

Using embedded plugins

SquashTM image, version 6.0.0 and later, embeds all the official SquashTM plugins.
As the image aims to be Kubernetes-ready, it is no longer needed to download and mount a volume with the plugins as jars.
It is replaced by a configmap to attach in the conf directory.

Attention

This only concerns the Docker image. The installer jar needs a manual installation of plugins.

In order to activate a plugin, the user needs to overdrive the config file in the path /opt/squash-tm/conf/start-plugins.cfg.
The file is located here or in the image at the given path.

To attach and override the existing file you can

in Docker, use volume: -v $(pwd)/conf/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg;

in Kubernetes, use configmap:

volumeMounts:
- name: plugins-config
  mountPath: /opt/squash-tm/conf/start-plugins.cfg
  subPath: start-plugins.cfg

To use a plugin, you need to uncomment the line that interest you, e.g.: |# apt-rest ---> |api-rest (where | is the beginning of the line).

Info

Although, all the official plugins are listed, if you want to use unlisted plugins, you can put your own in subdirectories in the folder /opt/squash-tm/plugins. (This is not the recommended and maintained way of using this image).

Here is a comprehensive list of available embedded plugins for each license, which can be activated during the deployment of SquashTM via a Docker image. To activate specific plugins, simply map the file as follows: path/to/your/file/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg. Feel free to comment out the plugins that you do not wish to utilize.

While the Ultimate license allows the use of community plugins, please note that it is not possible to use both types at the same time.

You can find the exhaustive list of plugins with their descriptions here as well as their downloadable versions here.
Once a plugin has been activated, it can only be removed manually.

CommunityPremiumUltimate

#### Autom-DevOps ####
scm-git

#### Bugtracker ####
bugzilla
gitlab

#### Synchronization ####
xsquash4gitlab

#### API ####
api-rest-admin

#### Autom-DevOps ####
scm-git

#### Bugtracker ####
azure-devops
bugzilla
gitlab
jiracloud
jiradatacenter
redmine
tuleap

#### Premium ####
squash-tm-premium

#### Report ####
campaign-execution

#### Security ####
ad
ldap
saml
openid-connect

#### Synchronization ####
redmine-requirements
xsquash4gitlab

#### Wizard ####
campaignassistant

#### API ####
api-rest-admin

#### Autom-DevOps ####
scm-git

#### Autom JIRA ####
workflow-automjira

#### Bugtracker ####
azure-devops
bugzilla
gitlab
jiracloud
jiradatacenter
redmine
tuleap

#### Premium ####
squash-tm-premium

#### Report ####
campaign-execution

#### Security ####
ad
ldap
saml
openid-connect

#### Synchronization ####
redmine-requirements
xsquash4gitlab

#### Wizard ####
campaignassistant

Data Backup with Persistent Volumes

The following volumes must be mounted to preserve the corresponding data:

database

/var/lib/postgresql/data     # Data location for PostgreSQL
/var/lib/mysql               # Data location for MariaDB

log files
```
/opt/squash-tm/logs
```
Xray imports queue
```
/opt/squash-tm/imports
```

For more information, refer to the Managing data in containers section in the Docker documentation.

Database environment variables

Since we often use images of existing DB containers, we highlight here a selection of relevant environment variables for convenience, and links to their documentation.

PostgreSQL image environment variables

`POSTGRES_PASSWORD`

This environment variable sets the superuser password for PostgreSQL. The default superuser is defined by the POSTGRES_USER environment variable.

`POSTGRES_USER`

This optional environment variable is used in conjunction with POSTGRES_PASSWORD to set a user and its password.
This variable will create the specified user with superuser power and a database with the same name. If it is not specified, then the default user of postgres will be used.

`POSTGRES_DB`

This optional environment variable can be used to define a different name for the default database created when it runs for the first time. If it is not specified, then the value of POSTGRES_USER will be used.

For further information and optional environment variables, please check out the PostgreSQL image documentation.

MariaDB image environment variables

`MARIADB_ROOT_PASSWORD`

This variable is mandatory and specifies the password that will be set for the MariaDB root superuser account.

`MARIADB_DATABASE`

This variable is optional and allows you to specify the name of a database to be created on image startup. If a user/password was supplied, then that user will be granted superuser access corresponding to GRANT ALL to this database.

`MARIADB_USER`, `MARIADB_PASSWORD`

These variables are optional, used in conjunction to create a new user and to set that user's password. This user will be granted superuser permissions (see above) for the database specified by the MARIADB_DATABASE variable. Both variables are required for a user to be created.

Do note that there is no need to use this mechanism to create the root superuser, that user gets created by default with the password specified by the MARIADB_ROOT_PASSWORD variable.

For further information and optional environment variables, please check out the MariaDB image documentation.

UID and GID

As of Squash TM 6.1.0 and onward, the main process will run as uid=1000 and gid=1000 (known as squashtm:squashtm within the container). Since Squash TM 1.21.4, the process ran as uid=100 and gid=101, and before that the user was root.

In case of a deployment with Kubernetes, if you're using a Security Context, the following values should be specified:

securityContext:
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000

Docker install

Quick Start

Configuring

Environment variables

Database access

Spring variables

SQTM_DB_* variables

Variable SQTM_DB_TYPE

Other useful variables

Timezone

App config using JAVA_TOOL_OPTIONS

App config using SPRING_APPLICATION_JSON

Deploying SquashTM

With PostgreSQL

With MariaDB

Docker Compose

docker-compose.yml file

.env file

init.sql file

Run Docker Compose

Install SquashTM license

Using SquashTM container with a reverse proxy

Kubernetes

Using embedded plugins

Data Backup with Persistent Volumes

Database environment variables

PostgreSQL image environment variables

POSTGRES_PASSWORD

POSTGRES_USER

POSTGRES_DB

MariaDB image environment variables

MARIADB_ROOT_PASSWORD

MARIADB_DATABASE

MARIADB_USER, MARIADB_PASSWORD

UID and GID

References

Variable `SQTM_DB_TYPE`

App config using `JAVA_TOOL_OPTIONS`

App config using `SPRING_APPLICATION_JSON`

`docker-compose.yml` file

`.env` file

`init.sql` file

`POSTGRES_PASSWORD`

`POSTGRES_USER`

`POSTGRES_DB`

`MARIADB_ROOT_PASSWORD`

`MARIADB_DATABASE`

`MARIADB_USER`, `MARIADB_PASSWORD`