Upgrade with an MSI Distribution
You can use the MSI distribution to upgrade any existing YouTrack Server installation.
The following software is bundled with the YouTrack Server MSI distribution:
Jetty servlet engine and HTTP server
Java SE Runtime Environment 11 x64
The MSI distribution does not include JRE x86. If you want to install YouTrack in an x86 environment, you will need to download and install the Java Runtime Environment that is compatible with your operating system.
The MSI installer requires .NET Framework version 2.0 or later.
Prerequisites
Before you upgrade, perform the following prerequisite tasks:
Create a backup of your current database. YouTrack Server does not provide forward database compatibility. Your database is migrated to the format that is compatible with the latest version during the upgrade procedure. This means that you cannot revert to a previous version and continue to use the database that was processed during the upgrade.
Copy the backup of your current database to a secure location just in case you encounter problems with the upgrade and need to roll back to the previous version.
Verify that your YouTrack license supports the upgrade. To view the license limitations, open the Administration menu and select , then select the License Details tab. If your free update period has expired, you need to extend your subscription.
Mind the recommended upgrade path.
Recommended Upgrade Path
Installation Version | Target Version |
---|---|
6.5 or earlier | YouTrack 7.0 |
7.0 | 2017.1 |
2017.x | 2018.x |
2018.x | 2019.x |
2019.x | 2020.x |
2020.x | 2021.x |
2021.x | current |
To locate the current version and build number for your YouTrack Server installation, open the Help menu in the application header
Upgrade an MSI Installation
If your YouTrack Server service was previously installed using an MSI distribution, you can use the MSI distribution to upgrade to the latest version of YouTrack Server.
The Windows Installer Package handles all the following upgrade procedures automatically:
Stops the currently running service.
Uninstalls the previous version.
Installs the new version.
Restarts the service.
To upgrade an existing MSI installation:
Download the MSI distribution from the JetBrains website.
Open the Windows Installer Package (MSI file).
The JetBrains YouTrack Setup Wizard opens.
Follow the instructions in the setup wizard.
When the setup wizard is finished, the web-based Configuration Wizard opens in your default browser.
If you do not have a web browser installed on the host machine, open the URL that is provided by the setup wizard in a web browser on another workstation.
Click the Finish button to close the setup wizard.
Switch to your web browser and continue with the upgrade installation in the web-based Configuration Wizard. The Configuration Wizard gives you the following options to continue with the upgrade:
Upgrade using the settings that were detected in the previous installation.
Select a different upgrade source. Use this option when you have another backup of your YouTrack Server database in a different location or want to use the location of another YouTrack Server installation as the upgrade source.
Discard the detected settings and perform a clean installation.
If you select a different upgrade source, verify that the service user account JetBrainsYouTrack has full access permissions to all the directories that are displayed in the wizard. This account is created by the installer to run the Windows service. If you continue without granting access to the JetBrainsYouTrack account, you encounter an error.
On the Confirm Settings page, confirm the basic system settings.
Setting
Description
Base URL
The URL where end users access YouTrack Server.
Application Listen Port
The port your YouTrack Server server listens to after installation.
Application Listen Address
The IP address that your YouTrack Server listens to after installation.
Data Directory Location
The directory where YouTrack Server stores content data.
Backup Location
The directory where YouTrack Server stores backups of the database.
Logs Location
The directory where YouTrack Server stores log files.
Temp Location
The directory where YouTrack Server stores product-specific temporary files.
To change the location for any of these file types, click the Change button and select a new location.
When done, click Upgrade.
The configuration is applied to your YouTrack Server server.
Do not close the page in the browser until the setup is complete.
When the YouTrack Server server is ready, the Dashboard opens. Your YouTrack Server instance is upgraded and ready for use.
Upgrade a non-MSI Installation with an MSI Distribution
You can upgrade any existing installation that was installed with a ZIP, Docker image, or JAR distribution and change the installation type to MSI at the same time.
Before you upgrade, create a backup of your current database.
To upgrade a ZIP or JAR installation with the MSI distribution:
Create and download a backup of your current YouTrack version.
Stop the YouTrack service. For specific instructions, see Stop and Start YouTrack.
Use your operating system tools to verify that all Java processes that are launched by YouTrack are no longer running. If there are YouTrack-related Java processes that are still running, interrupt the outstanding process trees.
Download the MSI distribution from the JetBrains website.
Open the Windows Installer Package (MSI file).
The JetBrains YouTrack Setup Wizard opens.
If the setup wizard detects data and configuration files from a previously installed version, select the recommended option to perform a clean installation.
The setup wizard displays this option when an earlier version of the MSI distribution was installed and later uninstalled on the server.
When the setup wizard is finished, the web-based Configuration Wizard opens in your default browser.
If you do not have a web browser installed on the host machine, open the URL that is provided by the setup wizard in a web browser on another workstation.
In the Configuration Wizard, click Upgrade.
On the Select Upgrade Source page, click the Select button and select the backup file that you created as the upgrade source.
Verify that the service user account JetBrainsYouTrack has full access permissions to all of the directories that are displayed in the wizard. This account is created by the installer to run the Windows service. If you continue without granting access to the JetBrainsYouTrack account, you encounter an error.
On the Confirm Settings page, confirm the basic system settings.
Setting
Description
Base URL
The URL where end users access YouTrack Server.
Application Listen Port
The port your YouTrack Server server listens to after installation.
Application Listen Address
The IP address that your YouTrack Server listens to after installation.
Data Directory Location
The directory where YouTrack Server stores content data.
Backup Location
The directory where YouTrack Server stores backups of the database.
Logs Location
The directory where YouTrack Server stores log files.
Temp Location
The directory where YouTrack Server stores product-specific temporary files.
To change the location for any of these file types, click the Change button and select a new location.
When done, click Upgrade.
The configuration is applied to your YouTrack Server server.
Do not close the page in the browser until the setup is complete.
When the YouTrack Server server is ready, the Dashboard opens. Your YouTrack Server instance is upgraded and ready for use.
Troubleshooting
If you encountered a problem and the installation failed, see if any of the following conditions apply.
Condition | The upgrade fails. The YouTrack service is not started. The database of your existing installation is not upgraded to the latest version. The installer rolls back to the previously installed version. |
---|---|
Cause | Undetermined. |
Solution |
|
Condition | The MSI installer successfully upgraded the installation to the new version, but the Configuration Wizard fails to open or reports an error. The YouTrack service fails to start. |
---|---|
Cause |
|
Solution |
If the upgrade failed, you can restore the previous version and continue working with YouTrack until the issue is resolved by our support team. For instructions, see the page that is relevant to your distribution type: |
Condition | The upgrade fails. YouTrack is already installed. The product code of the previous installation is displayed. The previous installation cannot be upgraded automatically. |
---|---|
Cause | YouTrack was previously installed with another administrator account. |
Solution |
Alternatively, you can move the previous installation to another server.
For further details, refer to the instructions provided in this YouTrack issue. |
Report a Problem with the Upgrade Installation
If you continue to experience problems with the upgrade installation:
Attach the following files to help us investigate and fix the issue:
Compress the contents of the
logs
directory and attach the ZIP archive. The default location of this directory is%programdata%\\JetBrains\YouTrack\logs
.If the location of this directory was changed in the Configuration Wizard, you can find the actual location in the
logs-dir
property of the%programdata%\\JetBrains\YouTrack\conf\internal\bundle.properties
file.Compress the contents of the
conf
directory and attach the ZIP archive. The default location of this directory is%programdata%\\JetBrains\YouTrack\conf
.Attach the
install.txt
file.
Our customer support engineers will investigate the issue and work with you to resolve the problem.