2.06 - Upgrade Squash TM

WARNING: before any modification, stop Squash TM

Users are provided with .sql upgrade scripts in each Squash TM release (see in /database-script ).

For Squash TM 1.13 and 1.14, the upgrade steps have been slightly modified.

For Squash TM 1.15, logging library had been upgraded, logging configuration file and startup script must be updated.

The upgrade database steps are described below, depending on the origin and destination versions.


Upgrade Squash TM from 1.14.2- to 1.15+

In Squash TM 1.15, logging library has been upgraded from Log4j to Log4j2. Logging configuration file must be updated.

The procedure has two steps:

  • logging configuration file migration
  • Squash TM startup script migration

The usual procedure must be followed as well (execution of SQL scripts to upgrade the database, substitution of configuration files if modified..., see "Upgrade Squash TM from 1.13+ to 1.13+" section below).

~SQUASH: Squash TM install repository

    1. Update the logging configuration file

  1. Copy conf/log4j2.xml from Squash TM 1.15 distrubution to ~SQUASH/conf/log4j2.xml
  2. If the logging configuration is customized, it must be migrated from Log4j to Log4j2 format (see https://logging.apache.org/log4j/2.x/manual/configuration.html#XML)
  3. Delete the former configuration file: conf/log4j.properties

NB: Log4j2 can be configured with several formats. Squash TM uses XML format by default. You can choose another format for Squash TM logging configuration but if you change the configuration file type, don't forget to type the correct name and extension in the Squash TM run command (see "Update the run script")

    2. Update the startup script

        a) Option 1: Replace the startup script

If Squash TM is deployed on a Windows environment:

  1. Save the file ~SQUASH/bin/startup.bat
  2. Replace this file with the one in Squash TM 1.15 distribution: /bin/startup.bat
  3. Copy the database configuration and every other modifications from the saved file to the new file ~SQUASH/bin/startup.bat

If Squash TM is deployed on a Linux or MacOS environment:

  1. Save the file ~SQUASH/bin/startup.sh
  2. Replace this file with the one in Squash TM 1.15 distribution: /bin/startup.sh
  3. Copy the database configuration and every other modifications from the saved file to the new file ~SQUASH/bin/startup.sh

        b) Option 2: Edit the startup script

If Squash TM is deployed on a Windows environment:

  1. Save the file ~SQUASH/bin/startup.bat to restore if necessary
  2. In the file ~SQUASH/bin/startup.bat, look for the following line:

  3. set DAEMON_ARGS=%JAVA_ARGS% -Djava.io.tmpdir=%TMP_DIR% -Dlogging.dir=%LOG_DIR% -jar %JAR_NAME% --spring.profiles.active=%DB_TYPE% --spring.config.location=file:%CONF_DIR%/squash.tm.cfg.properties --squash.path.root=%SQUASH-TM_HOME% --squash.path.bundles-path=%BUNDLES_DIR% --squash.path.plugins-path=%PLUGINS_DIR% --server.port=%HTTP_PORT% --server.tomcat.basedir=%TOMCAT_HOME% --hibernate.search.default.indexBase=%LUCENE_DIR% --logging.config=%CONF_DIR%/log4j.properties

  4. Edit the property:

     Former property
     New property
     --logging.config=%CONF_DIR%/log4j.properties  --logging.config=%CONF_DIR%/log4j2.xml


If Squash TM is deployed on a Linux or MacOS environment:

  1. Save the file ~SQUASH/bin/startup.sh to restore if necessary
  2. In the file ~SQUASH/bin/startup.sh, look for the following line:

    set DAEMON_ARGS=%JAVA_ARGS% -Djava.io.tmpdir=%TMP_DIR% -Dlogging.dir=%LOG_DIR% -jar %JAR_NAME% --spring.profiles.active=%DB_TYPE% --spring.config.location=file:%CONF_DIR%/squash.tm.cfg.properties --squash.path.root=%SQUASH-TM_HOME% --squash.path.bundles-path=%BUNDLES_DIR% --squash.path.plugins-path=%PLUGINS_DIR% --server.port=%HTTP_PORT% --server.tomcat.basedir=%TOMCAT_HOME% --hibernate.search.default.indexBase=%LUCENE_DIR% --logging.config=%CONF_DIR%/log4j.properties

  3. Edit the property:

     Former property
     New property
     --logging.config=%CONF_DIR%/log4j.properties  --logging.config=%CONF_DIR%/log4j2.xml


Upgrade Squash TM from 1.13+ to 1.13+

  1. Backup your database
  2. Run in the xxx growing order every 'DBType-upgrade-to-xxx.sql' script which number xxx is higher than the release number to be updated, and DBType is the type of your database.
  3. Follow the updated Squash installation instruction (see 2 - Installation of Squash TM)
  4. Copy and paste the former startup configuration file to the new release
  5. If modified, copy and paste the former conf/services file to the new file /conf/squash.tm.cfg.properties

Upgrade Squash TM from 1.12.6- to 1.13+

In TM 1.13, we switched from an OSGi container to a spring-boot based microservice container. From now on, the embedded servlet engine will be Tomcat instead of Jetty and it will offer more configurability. To upgrade a SquashTM installation from a version prior to 1.13 to a version after 1.13 please follow the steps :
  1. Backup your database
  2. Run in the xxx growing order every 'DBType-upgrade-to-xxx.sql' script which number xxx is higher than the release number to be updated, and DBType is the type of your database.
  3. Follow the updated Squash installation instruction (see 2 - Installation of Squash TM) 
  4. Plugins should all be upgraded to TM 1.13 compatible versions. Every plugin is now installed by dropping it in the ~SQUASH/plugins folder. Plugins installed in ~SQUASH/bundles will not be picked up by Squash TM.
  5. Migrating startup shell scripts (startup.bat for windows, startup.sh for linux)
    You should use the new shell scripts located in ~SQUASH/bin. In order to configure your application, you should refer to the variables table below. All variable with "unchanged" in 1.13+ column can be copied from your previous startup.bat/sh. 
    All relative paths are relative to the shell script's location i.e. ~SQUASH/bin. Unlisted variables should not be modified anyway. note that you must configure the variable DB_TYPE witch was not present before 1.13.

     Variable Name  up to 1.12.X  1.13 +
     JETTY_HOME  Jetty's work folder  Removed
     TOMCAT_HOME  n/a  Tomcat's work folder
     CACHE_DIR  Path to felix-cache  Removed
     LUCENE_DIR  Lucene indexes folder  unchanged
     TMP_DIR  Temp files folder  unchanged
     DB_URL  JDBC url of the database  unchanged
     DB_USERNAME  database user  unchanged
     DB_PASSWORD  database password  unchanged
     DB_DIALECT  Hibernate database dialect  removed
     DB_DRIVER  JDBC driver  removed
     DB_TYPE  n/a  one of : h2,mysql,postgresql

  6. Migrating configuration files

    Only 2 configuration files are needed in the ~SQUASH/conf folder : squash.tm.cfg.properties and log4j.properties
    These former configuration files are no longer used and can safely be removed : 

    felix.config.properties and felix.system.properties

    If you configured Squath TM using properties from any other ~SQUASH/conf/services/*.properties file, you should migrate these properties in ~SQUASH/conf/squash.tm.cfg.properties
     according to the following table. Properties which are not listed below should not be migrated. These were not configurable properties : they were not to be changed in any way.

     Former file name  Former property name  New property name  Note
     org.squashtest.csp.core.auth.config  authentication.provider  unchanged  See plugin documentation for additional properties
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.driverClassName  removed  Handled through DB_TYPE in shell script
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.url  spring.datasource.url  Not required when configured in shell script
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.username  spring.datasource.username  Not required when configured in shell script
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.password  spring.datasource.password  Not required when configured in shell script
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.validationQuery  spring.datasource.validation-query  Not required, sensible defaults applied
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.maxActive  spring.datasource.max-active  Not required, defaults to 10
     org.squashtest.csp.core.datasource.jdbc.config  datasource.db.initialSize  spring.datasource.initial-size  Not required, defaults to 2
     org.squashtest.csp.tm.hibernate.config  hibernate.dialect  removed  Handled through DB_TYPE in shell script
     squash.tm.cfg.properties  report.criteria.project.multiselect  unchanged  
     squash.tm.cfg.properties  squashtm.bugtracker.timeout  unchanged  
     tm.testautomation.conf  tm.test.automation.pollinterval.millis  unchanged  
     tm.testautomation.conf  tm.test.automation.server.callbackurl  unchanged  

Update Squash TM from version 1.12.6- to version 1.12.6-

To update the database, you will have to run all scripts 'bdd-upgrade-to-xxx.sql' where bdd is the type of your database, and xxx is higher than the version to update from (the scripts have to be run in the xxx growing order).

For example : for an upgrade from 1.0.2 to 1.1.1 on a MySQL database you need to run in this order :
  • mysql-upgrade-to-1.1.0.RELEASE.sql
  • mysql-upgrade-to-1.1.1.sql

BEWARE

Even though our upgrade scripts are thoroughly tested before each release, we strongly suggest that you back your database up.

To complete the update, you must index your datas :
  1. Connect as administrator on squash
  2. Go to administration workspace
  3. Click on [Index management]
  4. Click on [Index everything]
Your database is ready.

H2 database

In order to retrieve your data, you need a tool to connect to your h2 database. For example razor SQL will allow you to connect easily to you database (select H2 , then H2 embedded).
As soon as you are connected (squash>squashtm>data>squash-tm.h2.db), you will be able to run the migration scripts of the database (squash>squashtm>database-scripts> h2-upgrade-to-1.1.1.RELEASE.sql). 

FOCUS : Recommended

The embeded h2 database of Squash is not optimal for production maybe you should consider migrating to SQL (as seen here)



Properties files

Once the application is installed on your disk, you might want to import your previous server configuration (in the conf/services directory). A copy/paste is sufficient, except if there were changes or properties added in the new version. In this case you will be notified about it.

Clearing Cache

Finally you need to clear the browser cache for all the client machine for the domain hosting the instance of Squash TM. You can usually do this by pressing Ctrl + Shift + Suppr, then selecting the cached internet files. On the server it may also help to remove the 'felix-cache' directory, its location may vary depending on the system it runs on.




DEBIAN Upgrade

1. Stop Squash
2. Upgrade squash :
sudo apt-get upgrage squash-tm




REDHAT Upgrade

1. Stop Squash
2. Upgrade your database (see above)
3. Upgrade Squash :
sudo yum upgrade squash-tm