# 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
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 (opens new window) to quickly set up a production and shadow instance including a reverse proxy for zero-downtime deployments.
# Feature Version Updates with a Shadow Instance
Perform a full backup export of the configuration and external data via the Backup tab of the Admin perspective.
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.
Now you should have an empty Teamscale instance. Login as
adminusing the default password
Import the backup ZIP file into this instance via the Backup page of the Admin perspective.
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.
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.
Wait for the analysis to complete.
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.
To switch the two instances, first enable Shadow Mode in the production instance.
Export a full backup of the old production instance again.
Import this backup into the shadow instance but check the backup import option called Skip project creation and only update global data and data of existing projects (except project configuration).
Only for Shadow Instances
Never use the abovementioned backup import option on your production Teamscale instance. Only ever use it on your shadow instance.
The effect of this is that
- 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, blacklists, …).
- The projects are not reanalyzed.
After the backup was imported successfully, perform the switch of both 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.
If required, disable the Shadow Mode in the staging instance now to make Teamscale send notifications and votes again.