Skip to content

Docker install

Quick Start

Run the Squash TM image with an embedded h2 database (for demo purpose only !)

docker run --name='squash-tm' -it -p 8090:8080 squashtest/squash

NOTE: To run the container in daemon mode, use the -d option:

docker run --name='squash-tm' -d -it -p 8090:8080 squashtest/squash

Please allow a few minutes for the application to start, especially if populating the database for the first time. If you want to make sure that everything went fine, watch the log:

docker logs squash-tm -f

Go to http://localhost:8090/squash or point to the IP of your docker host.

The default username and password are:

  • username: admin
  • password: admin

Configuring

Environment variables

Database access

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

Notes:

  • (none): the variable is mandatory and has no default value
  • (special): see below
  • (*): experimental, should be stable but has not yet gone through thorough testing
  • (unused): the variable has no meaning for this database server. In the case of h2, those values are hardcoded to Squash TM default internal parameters

Variable SQTM_DB_TYPE

SQTM_DB_TYPE has an impact on the default values for several others. The best practice is to define it explicitly.
Be careful to type in the intended value correctly (eg postgresql and not 'postgres'), otherwise it won't start.
If no database is defined, the application will default to h2, which is not suited for production.

In previous versions of the image, this variable was internal only and its value was implied by the existence of other variables which are now deprecated (see below).
This mechanism is still functional: basically if SQTM_DB_TYPE is undefined but any variable of the form MARIADB_ENV_* or POSTGRES_ENV_* is configured then the value of SQTM_DB_TYPE will be implicitly resolved.
However, variables of the form SQTM_* will take precedence. Also be aware that this secondary mechanism will effectively stop working once the deprecated variables are removed eventually.

Other useful variables

Squash TM is a Spring Boot application; as such it benefits from its flexible configuration mechanism, see the documentation here.
We describe here two environment variables that could help you to configure your instance and possibly eliminate the need to manage the usual configuration files.

In addition to the properties specific to Squash TM, remember that the Spring platform itself can be configured too.
The reference can be found here and can help you adapt your container to your infrastructure, especially the server properties (which begin with the prefix server.).

Timezone

You can adjust your container's timezone settings with the TZ environment variable used by the package tzdata.

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

This standard variable in the Java world allows to customize the JVM process even when the command line is not readily available (which is the case here) and can be exploited to e.g. configure access through authenticated proxies etc.
Although originally intended to JVM tuning only, it can also be leveraged for application configuration.
Any property that could be defined in the regular configuration files can be defined in that environment variable instead.

Each pair of property=value must be prefixed with -D, and be separated by a space or other separator character.

There are a few caveats, however. Frustratingly, 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 Squash TM 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: Running Squash TM 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.enabled-by-default=true \
                  -Dmanagement.endpoints.web.exposure.include=*"

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

App config using SPRING_APPLICATION_JSON

This environment variable is another way to convey the configuration to the application. As the name implies, the configuration should be provided as a JSON string.
Unlike the variable JAVA_TOOL_OPTIONS, SPRING_APPLICATION_JSON cannot be used for JVM tuning (i.e. it supports Squash TM and Spring properties only), but offers interesting possibilities and more semantically satisfying than hacking around with JAVA_TOOL_OPTIONS.

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

Deploying Squash TM

The following sections show how to deploy Squash TM using an external PostgreSQL DB container or an external MariaDB container. Examples of yml file 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 Squash TM 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. 

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

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 bellow if you want to activate embedded plugins
#-v your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg \
-p 8090:8080 \
squashtest/squash

Wait 3-4 minutes the time for Squash TM 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 Squash TM 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. 

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.6 --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 bellow if you want to activate embedded plugins
#-v your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg \
-p 8090:8080 \
squashtest/squash

Wait several minutes while Squash TM initializes the database (mariadb initialisation is significantly longer than Postgres). 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 Squash TM to a MariaDB database. The environment variables should be set in a .env file (saved in the same repository as the docker-compose.yml).

version: '3.7'
services:
  squash-tm-md:
    image: mariadb:10.6
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_DATABASE: ${DB_DATABASE}
    volumes:
      - "/var/lib/mysql-db:/var/lib/mysql"

  squash-tm:
    image: squashtest/squash
    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}
    ports:
      - 8090:8080/tcp
    links:
      - squash-tm-md:mariadb
    volumes:
      - squash-tm-logs:/opt/squash-tm/logs
      # Uncomment bellow if you want to activate embedded plugins
      #- your/path/start-plugins.cfg:/opt/squash-tm/conf/start-plugins.cfg 

volumes:
  squash-tm-logs:

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)

Run a docker-compose

  1. Copy the docker-compose.yml that correspond to your need.
    You’ll find several docker-compose repository on our GitLab:

  2. Don’t forget to create an .env file (or set the value of environment variables directly in the docker-compose.yml file).

  3. In the docker-compose.yml directory, run docker-compose up or docker-compose up -d for daemon mode.

  4. Log in to http://localhost:8090/squash or http://{host_ip}:8090/squash.

For more information about docker-compose, here is the documentation.

Install Squash TM license

Instructions for installing Squash TM license is available here.

Using Squash TM container with a reverse proxy

Two examples of docker-compose.yml deploying Squash TM 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 Squash TM deployed behind a reverse-proxy using Postgres database:

version: '3.7'
services:
  squash-tm-pg:
    container_name: squash-tm-pg
    environment:
      POSTGRES_DB: ${DB_DATABASE}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USER}
    image: postgres:13
    volumes:
      - /var/lib/db-postgresql:/var/lib/postgresql/data
    networks:
      - db-network

  squash-tm:
    depends_on:
      - squash-tm-pg
    environment:
      SQTM_DB_USERNAME: ${DB_USER}
      SQTM_DB_PASSWORD: ${DB_PASSWORD}
      SQTM_DB_NAME: ${DB_DATABASE}
      VIRTUAL_HOST: mysquash.example.com
    ports:
      - 8090:8080/tcp
    image: squashtest/squash
    links:
      - squash-tm-pg:postgres
    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 Squash TM 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 Squash TM as configMap:

Modify the files 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, on the Squash TM k8s manifest uncomment the linked configuration.

kubectl apply -f ./squash-mariadb.yaml #Or postresql if you prefer

4) Access to the website:

  • On minikube:
sudo minikube tunnel #Mandatory to access the local loadbalancer

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

  • On k8s:
kubectl get svc

Get the correct External IP.
You can access Squash with the address http://:8080/squash.

Using embedded plugins

Squash TM image, version 6.0.0 and later, embeds all the official Squash TM 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 Squash 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.

#### Autom-DevOps ####
result-publisher
squashautom-community
testplan-retriever-community
scm-git

#### Bugtracker ####
bugzilla
gitlab

#### Report ####
report-books-pdf

#### Sync ####
xsquash4gitlab

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

#### Autom-DevOps ####
result-publisher
squashautom-community
testplan-retriever-community
scm-git

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

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

#### Report ####
report-books-pdf
campaign-execution

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

#### Sync ####
redmine-requirements
xsquash4gitlab

#### Wizard ####
campaignassistant

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

#### Autom-DevOps ####
result-publisher
squashautom-ultimate
# squashautom-community
testplan-retriever-ultimate
# testplan-retriever-community
workflow-automjira
workspace-actionword
scm-git

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

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

#### Report ####
report-books-pdf
campaign-execution

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

#### Sync ####
redmine-requirements
xsquash4gitlab

#### Wizard ####
campaignassistant

Backing up data with persistent volumes

As you may already know, in Docker you would generally keep data in volumes.

So, in order to use Squash TM image properly, it is highly recommended setting up an external database (MariaDB or PostgreSQL).

Each of these configurations provides the creation of a persistent volume for data.

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

Moreover, if your purpose is to use Squash TM image in production, you should persist the following location in a volume in order to keep traces of logs.

/opt/squash-tm/logs          # Log directory

For more info, check Docker docs section on Managing data in containers.

Appendix

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 Postgres 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 1.21.4 and onward, the main process will run as uid=100 and gid=101 (known as squashtm:squashtm within the container). In earlier versions, that user was root.

Deprecated environment variables

Versions 1.21.1 and earlier of this image defined a different set of variables which are now deprecated.

They are still accepted by newer images, therefore your former deployment descriptor will still work until further notice. Still, the variables listed in this table above remain the preferred way to configure it.

The only exception is MARIADB_ENV_MARIADB_ROOT_PASSWORD, which has been definitely removed and is not supported anymore.

When one of these deprecated variable is conflicting with its equivalent newer variable, the new variable will take precedence.

Deprecated MySQL/MariaDB specific environment variables

  • MYSQL_ENV_MYSQL_ROOT_PASSWORD: definitely removed
  • MYSQL_ENV_MYSQL_USER: equivalent of (and superseded by) SQTM_DB_USERNAME
  • MYSQL_ENV_MYSQL_PASSWORD: equivalent of (and superseded by) SQTM_DB_PASSWORD
  • MYSQL_ENV_MYSQL_DATABASE: equivalent of (and superseded by) SQTM_DB_NAME

Deprecated PostgreSQL specific environment variables

  • POSTGRES_ENV_POSTGRES_USER: equivalent of (and superseded by) SQTM_DB_USERNAME
  • POSTGRES_ENV_POSTGRES_PASSWORD: equivalent of (and superseded by) SQTM_DB_PASSWORD
  • POSTGRES_ENV_POSTGRES_DB: equivalent of (and superseded by) SQTM_DB_NAME

References