Aller au contenu

Installation Docker

Démarrage rapide

Lancez l'image Squash TM avec une base h2 embarquée (uniquement à des fins de démo !)

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

NOTE: Pour lancer le conteneur en mode daemon, utilisez l'option -d :

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

Attendez quelques minutes pour que l'application démarre, surtout si la base de données est peuplée pour la première fois. Pour vérifier que tout s'est bien passé, consultez les logs :

docker logs squash-tm -f

Allez à http://localhost:8090/squash ou pointez vers l'adresse IP de l'hôte docker.

Les login et mot de passe par défaut sont :

  • login : admin
  • mot de passe : admin

Configuration

Les sections suivantes montrent comment déployer Squash TM en utilisant un conteneur externe PostgreSQL DB ou MariaDB. Des exemples de fichiers yml montrent aussi comment déployer cette solution en utilisant docker-compose.

Variables d'environnement

Accès à la base de données

Variable Description H2 défaut MariaDB défaut Postgresql défaut
SQTM_DB_TYPE Soit 'h2', 'mariadb' ou 'postgresql' (special) (special) (special)
SQTM_DB_HOST Nom de l'hôte du serveur de base de données (unused) mariadb postgres
SQTM_DB_PORT Port du serveur de base de données (unused) 3306 5432
SQTM_DB_NAME Nom de la base de données (unused) squashtm squashtm
SQTM_DB_SCHEMA * Nom du schéma (unused) $DB_NAME public
SQTM_DB_USERNAME Username pour Squash-TM (unused) root root
SQTM_DB_PASSWORD Mot de passe pour Squash-TM (unused) (none) (none)

Notes:

  • (none) : la variable est obligatoire et n'a pas de valeur par défaut
  • (special) : voir ci-dessous
  • (*) : experimental, devrait être stable mais n'a pas encore fait l'objet de tests approfondis
  • (unused) : la variable n'a pas de signification pour ce serveur de base de données. Pour h2, ces valeurs sont codées en dur dans les paramètres internes par défaut de Squash TM

Variable SQTM_DB_TYPE

SQTM_DB_TYPE a un impact sur les valeurs par défaut de plusieurs autres variables. La bonne pratique est de la définir explicitement.
Veillez à saisir correctement la valeur souhaitée (par exemple postgresql et non 'postgres'), sinon l'application passera par défaut à h2 et pourrait tout de même démarrer avec succès, mais pas de la façon dont vous l'aviez prévu.

Dans les précédentes versions de l'image, cette variable était uniquement interne et sa valeur était impliquée par l'existence d'autres variables qui sont maintenant dépréciées (voir ci-dessous).
Ce mécanisme est toujours fonctionnel : si SQTM_DB_TYPE n'est pas définie mais que toute variable de la forme MARIADB_ENV_* ou POSTGRES_ENV_* est configurée, alors la valeur de SQTM_DB_TYPE sera implicitement résolue.
Néanmoins, la variables de la forme SQTM_* seront prioritaires. Sachez également que ce mécanisme secondaire cessera de fonctionner lorsque les variables dépréciées seront supprimées.

Autres variables utiles

Squash TM est une application Spring Boot; à ce titre, elle bénéficie d'un mécanisme de configuration flexible documentation ici.
Nous décrivons ici deux variables d'environnement qui pourraient vous aider à configurer votre instance et éventuellement à éliminer la nécessité de gérer les fichiers de configuration habituels.

En plus des propriétés spécifiques à Squash TM, n'oubliez pas que la plateforme Spring elle-même peut être configurée.
La référence peut être trouvée ici et peut vous aider à adapter votre conteneur à votre infrastructure, surtout les propriétés du serveur (qui commencent par le préfixe server.).

Fuseau horaire

Vous pouvez ajuster les paramètres du fuseau horaire de votre conteneur à l'aide de la variable d'environnement TZ utilisée par le paquet tzdata.

Par exemple, pour définir votre fuseau horaire à GMT +2, ajoutez le paramètre suivant à la commande docker run :

--env TZ=Europe/Paris

Configuration de l'application avec JAVA_TOOL_OPTIONS

Cette variable standard dans le monde Java permet de personnaliser le processus JVM même lorsque la ligne de commande n'est pas facilement disponible (ce qui est le cas ici) et peut être exploitée pour, par exemple, configurer l'accès via des proxys authentifiés, etc.
Bien que prévu à l'origine pour le réglage de la JVM uniquement, il peut également être exploité pour la configuration d'applications.
Toute propriété qui pourrait être définie dans les fichiers de configuration habituels peut être définie à la place dans cette variable d'environnement.

Chaque paire propery=value doit être préfixée par -D et séparée par un espace ou par un autre caractère de séparation.

Il y a cependant quelques réserves. Elle ne peut pas encore être utilisée pour configurer le heap size (cela fonctionne bien pour les autres flags de la JVM).
Une autre limitation est qu'elle ne peut par être complétée mais seulement redéclarée. Le dockerfile définit sa valeur par défaut à -Djava.awt.headless=true, qui est nécessaire parce que Squash TM fonctionne dans un environnement Linux non GUI. Si vous ne devez pas en tenir compte, n'oubliez pas de réintroduire manuellement ce paramètre (sinon vous risquez de rencontrer des problèmes lors de la génération et de l'export de rapports).
Ces inconvénients proviennent d'archaïsmes dans le script de démarrage et seront corrigés dans les prochaines versions.

Exemple: Lancer Squash TM avec le fuseau horaire des Fidji et activer tous les endpoints de Sprint Boot Actuator (à utiliser avec précaution, car cela exposera les paramètres sensibles !)

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

Configuration de l'application avec SPRING_APPLICATION_JSON

Cette variable d'environnment est une autre manière de transmettre la configuration à l'application. Comme son nom l'indique, la configuration devrait être fournie sous la forme d'un JSON string.
Contrairement à la variable JAVA_TOOL_OPTIONS, SPRING_APPLICATION_JSON ne peut pas être utilisée le réglade de la JVM (c'est-à-dire qu'elle ne prend en charge que les propriétés Squash TM et Spring), mais elle offre des possibilités intéressantes et plus satisfaisantes d'un point de vue sémantique que les contournements avec JAVA_TOOL_OPTIONS.

Exemple: activer la prise en charge du déchargement SSL

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

Déploiement de Squash TM

Avec PostgreSQL

La base de données est créée par le conteneur de la base de données et est automatiquement peuplée par le conteneur de l'application au premier lancement ou mise à jour si nécessaire lorsqu'une version plus récente de Squash-TM est déployée.

Toutes les données de la base de données seront sauvegardées dans le volume local nommé ‘squash-tm-db-pg’. De ce fait, le conteneur de base de données (appelé ‘squash-tm-pg’) peut être arrêté et redémarré sans risque de perte de données. 

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 -v squash-tm-plugins:/opt/squash-tm/plugins \
-p 8090:8080 \
squashtest/squash-tm

Attendez 3-4 minutes le temps que Squash-TM s'initialise. Ensuite, connectez-vous à http://localhost:8090/squash (admin / admin)

Avec MariaDB

LLa base de données est créée par le conteneur de la base de données et est automatiquement peuplée par le conteneur de l'application au premier lancement ou mise à jour si nécessaire lorsqu'une version plus récente de Squash-TM est déployée.

Toutes les données de la base de données seront sauvegardées dans le volume local nommé ‘squash-tm-db-mdb’. De ce fait, le conteneur de base de données (appelé ‘squash-tm-mdb’) peut être arrêté et redémarré sans risque de perte de données. 

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 \
-v squash-tm-plugins:/opt/squash-tm/plugins \
-p 8090:8080 \
squashtest/squash-tm

Attendez plusieurs minutes le temps que Squash-TM initialise la base de données (l'initialisation de mariadb est sensiblement plus longue que postres). Ensuite, connectez-vous à http://localhost:8090/squash (admin / admin).

Docker-Compose

Fichier docker-compose.yml

L'exemple suivant de docker-compose.yml lie Squash TM à une base de données MariaDB. Les variables d'environnement doivent être définies dans un fichier .env (enregistré dans le même dépôt que le fichier 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-tm
    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
      - squash-tm-plugins:/opt/squash-tm/plugins

volumes:
  squash-tm-logs:
  squash-tm-plugins:

Et le fichier .env :

DB_USER=squashtm
DB_PASSWORD=MustB3Ch4ng3d
DB_DATABASE=squashtm

Exécuter un docker-compose

  1. Copiez le docker-compose.yml qui correspond à votre besoin.
    Vous trouverez plusieurs répertoires docker-compose sur notre Gitlab:

  2. N'oubliez pas de créer un fichier .env (ou de définir la valeur des variables d'environnement directement dans le fichier docker-compose.yml).

  3. Dans le répertoire de docker-compose.yml, exécuter docker-compose up ou docker-compose up -d pour le mode daemon.

  4. Connectez-vous à http://localhost:8090/squash ou http://{host_ip}:8090/squash

Pour plus d'information au sujet de docker-compose, voici la documentation.

Installation de la licence et des plugins Squash TM

Les instructions pour l'installation de la licence et des plugins Squash TM sont disponibles ici.

Utilisation du conteneur Squash TM avec un reverse proxy

Deux exemples de docker-compose.yml permettant de déployer Squash TM derrière un reverse proxy sont disponibles sur notre Gitlab:

Ces solutions utilisent une image docker de jwilder basée sur nginx-proxy.

Voici un exemple de Squash TM déployé derrière un reverse-proxy en utilisant une base de données Postres :

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-tm
    links:
      - squash-tm-pg:postgres
    volumes:
      - squash-tm-logs:/opt/squash-tm/logs
      - squash-tm-plugins:/opt/squash-tm/plugins
    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:
  squash-tm-plugins:

networks:
  nginx-proxy:
  db-network:

Et le fichier .env :

DB_USER=squashtm
DB_PASSWORD=MustB3Ch4ng3d
DB_DATABASE=squashtm

Sauvegarde des données avec des volumes persistants

Comme vous le savez peut-être déjà, dans Docker, les données sont généralement conservées dans des volumes.

Ainsi, afin d'utiliser correctement l'image Squash TM, il est fortement recommandé de configurer une base de données externe (MariaDB ou PostgreSQL).

Chacune de ces configurations permet de créer un volume persistant pour les données.

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

De plus, si votre objectif est d'utiliser l'image de Squash TM en production, il sera probablement pertinent de conserver l'emplacement suivant dans un volume afin de garder des traces des logs. 

/opt/squash-tm/logs          # Log directory

Pour plus d'informations, consultez la section Managing data in containers dans la documentaiton Docker.

Annexes

Variables d'environnement des bases de données

Etant donnée que nous utilisons souvent des images de conteneurs de base de données existants, nous mettons ici en évidence une sélection de variables d'environnement pertinentes pour plus de commodité, ainsi que des liens menant à leur documentation.

Variables d'environnement de l'image Postgres

POSTGRES_PASSWORD

Cette variable d'environnement définit le mot de passe du superutilisateur pour PostgreSQL. Le superutilisateur par défaut est défini par la variable d'environnement POSTGRES_USER.

POSTGRES_USER

Cette variable d'environnement optionnelle est utilisée en conjonction avec POSTGRES_PASSWORD pour définir un utilisateur et son mot de passe.
Cette variable créera l'utilisateur spécifié avec le pouvoir de super-utilisateur et une base de données avec le même nom. Si elle n'est pas spécifiée, l'utilisateur par défaut postgres sera utilisé.

POSTGRES_DB

Cette variable d'environnement optionnelle peut être utilisée pour définir un nom différent pour la base de données par défaut créée lors de la première exécution. Si elle n'est pas spécifiée, la valeur de POSTGRES_USER sera utilisée.

Pour plus d'informations et de variables d'environnement optionnelles, consultez la documentation de l'image Postgres.

Variables d'environnement de l'image MariaDB

MARIADB_ROOT_PASSWORD

Cette variable est obligatoire et spécifie le mot de passe qui sera défini pour le compte superutilisateur root de MariaDB.

MARIADB_DATABASE

Cette variable est facultative et vous permet de spécifier le nom d'une base de données à créer au démarrage de l'image. Si un utilisateur et un mot de passe ont été fournis, cet utilisateur se verra accorder l'accès superutilisateur correspondant à GRANT ALL sur cette base de données.

MARIADB_USER, MARIADB_PASSWORD

Ces variables sont optionnelles, utilisées conjointement pour créer un nouvel utilisateur et définir son mot de passe. Cet utilisateur se verra accorder les permissions de superutilisateur (voir ci-dessus) pour la base de données spécifiée par la variable MARIADB_DATABASE. Ces deux variables sont nécessaires pour créer un utilisateur.

Notez qu'il n'est pas nécessaire d'utiliser ce mécanisme pour créer le superutilisateur root, cet utilisateur est créé par défaut avec le mot de passe spécifié par la variable MARIADB_ROOT_PASSWORD.

Pour plus d'informations et pour connaître les variables d'environnement optionnelles, consultez la documentationde l'image MariaDB.

UID et GID

A partir de Squash-TM 1.21.4, le processus principal s'exécutera tant que uid=100 et gid=101 (connu sous le nom de squashtm:squashtm à l'intérieur du conteneur). Dans les versions antérieures, cet utilisateur est root.

Variables d'environnement dépréciées

Les versions 1.21.1 et antérieures de cette image définissaient un ensemble différent de variables qui sont désormais dépréciées.

Elles sont toujours acceptées par les images plus récentes, donc votre ancien descripteur de déploiement fonctionnera toujours jusqu'à nouvel ordre. Cependant, les variables listées dans ce tableau ci-dessus restent la meilleure façon de le configurer.

La seule exception est MARIADB_ENV_MARIADB_ROOT_PASSWORD, qui a été définitivement supprimée et n'est plus supportée.

Lorsque l'une de ces variables dépréciées est en conflit avec une variable équivalente plus récente, c'est la nouvelle variable qui a la priorité.

Variables d'environnement spécifiques à MySQL/MariaDB dépréciées

  • MYSQL_ENV_MYSQL_ROOT_PASSWORD: définitivement supprimée
  • MYSQL_ENV_MYSQL_USER: équivalent de (et remplacée par) SQTM_DB_USERNAME
  • MYSQL_ENV_MYSQL_PASSWORD: équivalent de (et remplacée par) SQTM_DB_PASSWORD
  • MYSQL_ENV_MYSQL_DATABASE: équivalent de (et remplacée par) SQTM_DB_NAME

Variables d'environnement spécifiques à Postgresql dépréciées

  • POSTGRES_ENV_POSTGRES_USER: équivalent de (et remplacée par) SQTM_DB_USERNAME
  • POSTGRES_ENV_POSTGRES_PASSWORD: équivalent de (et remplacée par) SQTM_DB_PASSWORD
  • POSTGRES_ENV_POSTGRES_DB: équivalent de (et remplacée par) SQTM_DB_NAME

Remontées d'anomalies

Veuillez déclarer des anomalies sur https://ci.squashtest.org/ or contact@squashtest.com.

En plus des informations pertinentes (environnement, étapes pour reproduire, etc.), vous devriez également mentionner la valeur du Docker label DOCKER_BUILD_GIT_REVISION s'il existe (à partir de la version 1.21.4) :

docker inspect <your image> | grep DOCKER_BUILD_GIT_REVISION

Références