Docker install

Quick Start

To quickly play with SquashTM:

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

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

   services:
     squashtm-pg:
       container_name: squashtm-pg
       environment:
         POSTGRES_DB: squashtm
         POSTGRES_USER: squashtm
         POSTGRES_PASSWORD: MustB3Ch4ng3d
       image: postgres:17
       ports:
         - 5432:5432
   
     squashtm:
       container_name: squashtm
       image: squashtest/squash:14.0.4
       depends_on:
         - squashtm-pg
       environment:
         SPRING_PROFILES_ACTIVE: postgresql
         SPRING_DATASOURCE_URL: jdbc:postgresql://squashtm-pg:5432/squashtm
         SPRING_DATASOURCE_USERNAME: squashtm
         SPRING_DATASOURCE_PASSWORD: MustB3Ch4ng3d
       ports:
         - 8090:8080
       volumes:
         - squashtm-logs:/opt/squash-tm/logs
   
   volumes:
     squashtm-logs:
   

3. Execute the command docker compose up.

4. 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:

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

Spring variables

These settings are described here.

SQTM_DB_* variables

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 other 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 Europe/Paris, 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:14.0.4

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

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 squashtm-db-pg. So the db container (called squashtm-pg) can be stopped and restarted with no risk of losing them.

docker network create squashtm-postgresql

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

sleep 10

docker run -it -d --name=squashtm \
--network squashtm-postgresql \
-e SPRING_PROFILES_ACTIVE=postgresql \
-e SPRING_DATASOURCE_USERNAME=squashtm \
-e SPRING_DATASOURCE_PASSWORD=MustB3Ch4ng3d \
-e SPRING_DATASOURCE_URL=jdbc:postgresql://squashtm-pg:5432/squashtm \
-v squashtm-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:14.0.4

docker network create squashtm-postgresql

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

sleep 10

docker run -it -d --name=squashtm \
--network squashtm-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=squashtm-pg \
-v squashtm-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:14.0.4

Wait for a few minutes for SquashTM to initialize.
Then, log in to http://localhost:8090/squash (admin / admin)

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 squashtm-db-mdb. So the db container (called squashtm-mdb) can be stopped and restarted without risk of losing data.

docker network create squashtm-mariadb

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

sleep 10

docker run -it -d --name=squashtm \
--network squashtm-mariadb \
-e SPRING_PROFILES_ACTIVE=mariadb \
-e SPRING_DATASOURCE_USERNAME=squashtm \
-e SPRING_DATASOURCE_PASSWORD=MustB3Ch4ng3d \
-e SPRING_DATASOURCE_URL=jdbc:mariadb://squashtm-mdb:3306/squashtm \
-v squashtm-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:14.0.4

docker network create squashtm-mariadb

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

sleep 10

docker run -it -d --name=squashtm \
--network squashtm-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=squashtm-mdb \
-v squashtm-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:14.0.4

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

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

services:
  squashtm-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"


  squashtm:
    image: squashtest/squash:14.0.4
    depends_on:
      - squashtm-md
    environment:
      SPRING_PROFILES_ACTIVE: mariadb
      SPRING_DATASOURCE_URL: jdbc:mariadb://squashtm-md:3306/${DB_DATABASE}
      SPRING_DATASOURCE_USERNAME: ${DB_USER}
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
    ports:
      - 8090:8080
    volumes:
      - squashtm-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:
  squashtm-logs:

services:
  squashtm-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"


  squashtm:
    image: squashtest/squash:14.0.4
    depends_on:
      - squashtm-md
    environment:
      SQTM_DB_TYPE: mariadb
      SQTM_DB_USERNAME: ${DB_USER}
      SQTM_DB_PASSWORD: ${DB_PASSWORD}
      SQTM_DB_NAME: ${DB_DATABASE}
      SQTM_DB_HOST: squashtm-md
      SQTM_DB_PORT: "3306"
    ports:
      - 8090:8080
    volumes:
      - squashtm-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:
  squashtm-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;

Run Docker Compose

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

   • SquashTM deployment using MariaDB database
   • SquashTM deployment using PostgreSQL database
   • SquashTM deployment using PostgreSQL database and Reverse-Proxy
   • SquashTM deployment using MariaDB database and Reverse-Proxy

2. Do not 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 SquashTM license

Instructions for installing a SquashTM license are 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:

• SquashTM deployment using PostgreSQL database and Reverse-Proxy
• SquashTM deployment using MariaDB database and Reverse-Proxy

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

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

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

  squashtm:
    depends_on:
      - squashtm-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: squashtm-pg
    ports:
      - 8090:8080
    image: squashtest/squash:14.0.4
    volumes:
      - squashtm-logs:/opt/squash-tm/logs
      # Uncomment below 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:
  squashtm-logs:

networks:
  nginx-proxy:
  db-network:

And the .env file:

DB_USER=squashtm
DB_PASSWORD=MustB3Ch4ng3d
DB_DATABASE=squashtm

Kubernetes

A Kubernetes manifest of SquashTM can be found here.

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

1. Premium only: Create a secret from a 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 according to the documentation:

   • start-plugins.cfg is described 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 Kubernetes manifest.

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

4. Access to SquashTM:

   KubernetesMinikube

   kubectl get svc
   

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

   sudo minikube tunnel # Mandatory to access the local load balancer
   

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

Plugin configuration

The SquashTM Docker image contains all the SquashTM plugins.

In order to activate a plugin, the user needs to override the config file in the path /opt/squash-tm/conf/start-plugins.cfg:

• in Docker, use a 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 by removing the hash character (#) at the beginning of the line: # api-rest becomes api-rest.

Here is a comprehensive list of available plugins for each license (their descriptions are available here):

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

Importing a Certificate

1. Get the certificate and save it in a certs subdirectory.

2. In that certs subdirectory, create an import-certs.sh script file having this content:

   #!/bin/sh
   set -e
   
   CERT_DIR="/tmp/certs"
   CACERTS_PATH=$(find /opt/java /usr/lib/jvm -name cacerts 2>/dev/null | head -n 1)
   
   if [ -z "$CACERTS_PATH" ]; then
       echo "ERROR: cacerts not found"
       exit 0
   fi
   
   echo "===== Importing SSL certificates ====="
   echo "Using cacerts: $CACERTS_PATH"
   
   for cert in "$CERT_DIR"/*.crt "$CERT_DIR"/*.cer "$CERT_DIR"/*.pem; do
       [ -f "$cert" ] || continue
   
       ALIAS=$(basename "$cert" | sed 's/\.[^.]*$//')
   
       # Check if the certificate already exists
       if keytool -list -keystore "$CACERTS_PATH" -storepass changeit -alias "$ALIAS" >/dev/null 2>&1; then
           echo "✓ Certificate $ALIAS already exists, skipped"
           continue
       fi
   
       # Import the certificate
       echo "→ Importing certificate: $ALIAS"
       if keytool -import -trustcacerts \
           -alias "$ALIAS" \
           -file "$cert" \
           -keystore "$CACERTS_PATH" \
           -storepass changeit \
           -noprompt; then
           echo "✓ Certificate $ALIAS imported successfully"
       else
           echo "✗ Failed to import $ALIAS, continuing..."
       fi
   done
   
   echo "===== Certificate import completed ====="
   

   Set this file as executable.

3. Modify the docker-compose.yml file by adding in it:

   • a bind mount: ./certs:/tmp/certs:ro
   • an entry point: ["/bin/sh", "-c", "[ -f /tmp/certs/import-certs.sh ] && /tmp/certs/import-certs.sh ; /sbin/tini -- /bin/sh -c /opt/install-script.sh"]

   For example:

   services:
     squashtm-pg:
       container_name: squashtm-pg
       environment:
         POSTGRES_DB: squashtm
         POSTGRES_USER: squashtm
         POSTGRES_PASSWORD: MustB3Ch4ng3d
       image: postgres:17
       ports:
         - 5432:5432
   
     squashtm:
       container_name: squashtm
       image: squashtest/squash:14.0.4
       entrypoint: ["/bin/sh", "-c", "[ -f /tmp/certs/import-certs.sh ] && /tmp/certs/import-certs.sh ; /sbin/tini -- /bin/sh -c /opt/install-script.sh"]
       depends_on:
         - squashtm-pg
       environment:
         SPRING_PROFILES_ACTIVE: postgresql
         SPRING_DATASOURCE_URL: jdbc:postgresql://squashtm-pg:5432/squashtm
         SPRING_DATASOURCE_USERNAME: squashtm
         SPRING_DATASOURCE_PASSWORD: MustB3Ch4ng3d
       ports:
         - 8090:8080
       volumes:
         - squashtm-logs:/opt/squash-tm/logs
         - ./certs:/tmp/certs:ro
   
   volumes:
     squashtm-logs:
   

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.

Appendices

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

References

• GitLab repository of SquashTM docker sources
• PostgreSQL image documentation
• MariaDB image documentation
• jwilder/nginx-proxy documentation