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 System Settings > Global Settings, then select the License Details tab. If your free update period has expired, you need to extend your subscription.
Mind the recommended upgrade path. The current version of your installation is shown at the bottom of almost every page in the application (not on agile boards).

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

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

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.
Uninstall the previous non-MSI version.

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	Run the MSI installer with verbose logging enabled. In the Command Prompt window, enter the following command: `msiexec /i youtrack-xxxxx.msi /l*v install.txt` The installer writes the verbose log data to a file named `install.txt` and saves it in your current directory. Review the contents of the `install.txt` log file. The failure report begins with the string `Return value 3`. If the log file indicates that there was a service startup failure, check the YouTrack log files for errors. The default location of the YouTrack log files is `%programdata%\\JetBrains\YouTrack\logs` If you can identify and correct the problem yourself, repeat the upgrade procedure. Otherwise, create an issue in the YouTrack project.

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

Run the MSI installer with verbose logging enabled. In the Command Prompt window, enter the following command:
msiexec /i youtrack-xxxxx.msi /l*v install.txt
The installer writes the verbose log data to a file named install.txt and saves it in your current directory.
Review the contents of the install.txt log file. The failure report begins with the string Return value 3.
If the log file indicates that there was a service startup failure, check the YouTrack log files for errors. The default location of the YouTrack log files is %programdata%\\JetBrains\YouTrack\logs
If you can identify and correct the problem yourself, repeat the upgrade procedure. Otherwise, create an issue in the YouTrack project.

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	The specified port is occupied by another service. You do not have access permissions to update files and folders in the installation directory.
Solution	Check the log files, particularly `service.log`, for errors. The default location of the log files is `%programdata%\\JetBrains\YouTrack\logs` If you can identify and correct the problem (for example, change the port number or obtain access to the installation directory), repeat the upgrade procedure as follows. Perform a clean installation of the new version. On the Upgrade Source page, select a backup copy of the database from the previous version. Otherwise, create an issue in the YouTrack project. 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: Restore a Docker Installation Restore a JAR Installation Restore an MSI Installation Restore a ZIP Installation

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

The specified port is occupied by another service.
You do not have access permissions to update files and folders in the installation directory.

Solution

Check the log files, particularly service.log, for errors. The default location of the log files is %programdata%\\JetBrains\YouTrack\logs
If you can identify and correct the problem (for example, change the port number or obtain access to the installation directory), repeat the upgrade procedure as follows.
- Perform a clean installation of the new version.
- On the Upgrade Source page, select a backup copy of the database from the previous version.
Otherwise, create an issue in the YouTrack project.

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	Log in to the previous version of YouTrack and create a backup of your database. Either ask the administrator who performed the installation to uninstall the previous version or reset the administrator account credentials and uninstall the previous version yourself. You can use administration tools like the Event Viewer or Registry to find the user account that was used to install the previous version. Alternatively, you can move the previous installation to another server. Perform a clean installation of YouTrack. Select the option to remove the previous configuration. In the Configuration Wizard, select the backup of the previous version as the upgrade source. For further details, refer to the instructions provided in this YouTrack issue.

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

Log in to the previous version of YouTrack and create a backup of your database.
Either ask the administrator who performed the installation to uninstall the previous version or reset the administrator account credentials and uninstall the previous version yourself. You can use administration tools like the Event Viewer or Registry to find the user account that was used to install the previous version.

Alternatively, you can move the previous installation to another server.

Perform a clean installation of YouTrack. Select the option to remove the previous configuration.
In the Configuration Wizard, select the backup of the previous version as the upgrade source.

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:

Create an issue in the YouTrack project.
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.

Last modified: 21 September 2022