Teamscale Docs

Appearance

How to Set up a Shadow Instance ​

Re-analyzing a Teamscale project can take some time if you analyze a lot of data (code, findings, coverage, ...). When updating a Teamscale instance to a new feature version, you have to re-analyze all your projects to take advantage of all new features and bug fixes. On large instances, re-analyzing all projects may take up to several days.

Therefore, it is inadvisable to just shut down your running Teamscale instance and then start a fresh one, as this will mean a longer downtime where Teamscale cannot be used.

Instead, we recommend you run two instances in parallel during updates: the production instance and a shadow instance. This allows your users to still access the old version of Teamscale while the new one is still analyzing.

In the simplest case, you can just set up a shadow instance running on another port on the same server as the production instance (see file config/teamscale.properties). As soon as the new instance has finished re-analyzing the projects, the old instance can be shut down and the port of the new instance can be set to match the old one.

If you want zero downtime, you can use a tool like NGINX and configure it as a reverse proxy.

In a Docker-based setup, you can use our template GitHub repository to quickly set up a production and shadow instance including a reverse proxy for zero-downtime deployments.

Feature Version Updates with a Shadow Instance ​

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

  2. Create a new shadow instance with the new feature version. Copy the config files from the previous version to the config folder of the newly created instance. 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.

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

  4. Import the backup ZIP file into this instance via the Backup view of the Admin perspective.

  5. 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 or voting to other systems will happen.

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

  7. Wait for the analysis to complete.

  8. Optional: Before switching from the old production instance to the shadow instance, we recommend you perform a short instance comparison to compare the analysis results of the two instances and check for unexpected changes or inconsistencies. For this, create a new instance comparison in the shadow instance under Admin > Instance Comparison.

During the time it took Teamscale to reanalyze all projects, users might have changed dashboards, their settings, issue queries, etc. Furthermore, external analysis results (coverage, build results, external findings, …) might have been uploaded to the old production instance. We don’t want to lose all these changes when we switch over to the new Teamscale version. So before the switch we have to transfer this delta in Teamscale’s data over to the shadow instance, but without reanalyzing all projects.

  1. To switch the two instances, first enable Shadow Mode in the production instance.

  2. Export a full backup of the old production instance again.

  3. Import this backup into the shadow instance but check the backup import option called Skip new projects and only update global data and data of existing projects (except project configuration).

The effects of this are:

  • All global data in the new production instance is updated to match the old production instance (i.e. users, dashboards, account settings, …).
  • External analysis results and settings of each project are updated to match the old production instance (e.g. issue queries, finding tolerations, …).
  • The projects are not reanalyzed.

  1. After the backup was imported successfully, perform the switch of the instances in your reverse proxy right away (you don’t have to wait for any further analysis work to complete). Thus, the users see no interruption in their normal usage of Teamscale and keep all their data.

  2. Disable the Shadow Mode in the staging instance now to make Teamscale send notifications and votes again.