How to Perform a Feature Version Update

Feature version updates are updates where one of the first two parts of the version number changed. For example, an update from version 9.3.3 to 9.4.0 would be considered a feature version update.

Avoid Downtimes with a Shadow Instance

For large instances, we recommend you use a shadow instance to perform these updates. This avoids unnecessary downtimes during the update process.

Re-analysis required

As the format of the internal database may change and also new checks become available, a full analysis is required after a feature version update.

This may take some time, depending on the amount of data you have imported into Teamscale (code, findings, coverage, ...). For large instances, we strongly recommend you perform the update with a shadow instance.

Docker Deployments

The following steps are specific for using Docker to deploy Teamscale and are based on our reference configuration.

The detailed steps are as follows:

1. Perform a full backup export of the configuration and external data via the Backup tab of the Admin perspective.
2. Add a new directory named according to the version, e.g. v7.8.
3. Copy the config directory (containing teamscale.license and teamscale.properties ) from the production instance to v7.8 and adjust any configuration (e.g. workers, memory)
4. Add a new service entry in docker-compose.yml, e.g. by coping the entry from v7.7 adjust the image to the new release, e.g. cqse/teamscale:7.8.latest change the volume mount to the newly created folder, e.g. ./v7.8/:/var/teamscale/
5. Reference the v7.8 Docker service in the staging server section of nginx/teamscale.conf (set $teamscale_next v7.8;)
6. Start the v7.8 Docker service using sudo ./start.sh. Now you should have an empty Teamscale instance. Login as admin using the default password admin.
7. Import the backup ZIP file into this instance via the Backup page of the Admin perspective.
8. If you were using the default settings during backup import, the instance will now be in Shadow Mode which means that no external events, such as notification emails of voting to other production systems will happen.
9. You may have to delete the default administrative user (admin) after importing the backup as it is always created when starting Teamscale on an empty storage directory.
10. Wait for the analysis to complete.
11. If required, disable the Shadow Mode now to make Teamscale send notifications and votes again.
12. Update the production server section of nginx/teamscale.conf to reference the previous staging Teamscale server (e,g. set $teamscale_prod v7.8;)
13. Reload the nginx configuration by executing sudo ./nginx-reload.sh

Zip-based Installations

The following steps are specific for zip-based installations and do not apply if you are using Docker to deploy Teamscale.

Always Unzip on Target System

Always unzip the downloaded ZIP file on the system that you want to install Teamscale on. Otherwise, if the ZIP is, for example, unzipped under Windows and then copied to Linux, Teamscale may later fail to start (as Unix permissions like executable can get lost).

The detailed steps are as follows:

1. Perform a full backup export of the configuration and external data via the Backup tab of the Admin perspective.

2. Stop Teamscale. This depends on how you installed Teamscale and may require you to stop a service or kill the Teamscale process.

3. It is strongly recommended to create a backup of the Teamscale installation and storage directories, so you can return to the current version if anything does not work as expected.

4. Replace the Teamscale installation with the new one. For this you should rename/remove the old Teamscale installation directory and extract the new version to the same place Teamscale was installed before. If you delete the old directory, make sure to keep the config folder and to copy it back to the new directory. Under Windows, do the same for the windows folder. After extraction, the overall file layout should look the same as before.

Do not copy/extract the new Teamscale files over the old ones

Copying/Extracting the new Teamscale files over the old ones is not supported and will break your installation, e.g. by overwriting configuration changes you have made or by not removing old files that should be deleted during the update. You should instead always unzip the new Teamscale files into a separate directory and copy your configuration files from the old directory as described above.

5. Also delete the storage directory, if this is outside of your Teamscale installation directory. In case you have configured an external data directory (workspace), make sure to delete this as well.

6. Copy the config files from the previous version to the config folder of the newly extracted version. Under Windows, do the same for the files in the windows folder. You might need to adjust the configuration if the format changed. This will be described at the download site of Teamscale if required.

7. Start Teamscale. Depending on the installation this may require starting the corresponding service or running the start script.

8. Now you should have an empty Teamscale instance. Login as admin using the default password admin.

9. Import the backup ZIP file into this instance via the Backup page of the Admin perspective.

10. If you were using the default settings during backup import, the instance will now be in Shadow Mode which means that no external events, such as notification emails of voting to other systems will happen.

11. You may have to delete the default administrative user (admin) after importing the backup as it is always created when starting Teamscale on an empty storage directory.

12. Wait for the analysis to complete.

13. If required, disable the Shadow Mode now to make Teamscale send notifications and votes again.