# How to Update Teamscale

This section describes how to migrate user- and project-specific data from an existing installation to newer versions of Teamscale. Please note that the steps in this guide are for a normal installation 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).

# Patch Version Updates

Patch version updates are updates where the first two parts of the version number stay the same. For example, an update from version 4.7.2 to the newer version 4.7.4 would be considered a patch version update.

TIP

Unless explicitly stated in the changelog, patch version updates are fully compatible, which means that all configuration files and the database do not need to be modified and thus no re-analysis is needed.

To perform a patch version update, follow these steps:

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

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

  3. Replace the Teamscale installation with the new one. For this you should rename/remove the existing files in the Teamscale installation directory and extract the new version there. Make sure to preserve the files from the config directory and also preserve the contents of the storage and workspace directories, if they are within the installation directory. After extraction, the overall file layout should look the same as before.

  4. Copy the config files from the previous version to the config folder of the newly extracted version.

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

After this, Teamscale should be running with the new version and the existing data. No re-analysis is required, unless the hot-fix version provides fixes for bugs that you want to apply to the entire history of a project.

# Feature Version Updates

This section describes the general procedure for migrating from previous versions of Teamscale that is also applicable for feature version updates.

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.

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 existing files in the Teamscale installation directory and extract the new version there. Make sure to preserve the files from the config directory. Under Windows, also preserve the files in the windows directory. After extraction, the overall file layout should look the same as before.

  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. Import the backup ZIP file into this instance via the Backup page of the Admin perspective.

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

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

  11. Wait for the analysis to complete.

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

Updating without downtime

Note that due to the required re-analysis, there might be a significant time where Teamscale does not yet provide the results for the current head revision. To mitigate this, we recommend a setup with two separate instances, one life instance and one shadow instance, for production use. For an update, you update the shadow instance first, and then switch instances after the analysis was completed. For more details see our blog article on this subject.