YouTrack Standalone 2017.3 Help

Upgrade with an MSI Distribution

You can use the MSI distribution to upgrade an existing YouTrack Standalone installation that was installed with an MSI or ZIP distribution as a Windows Service.

The following software is bundled with the YouTrack Standalone MSI distribution:

  • Jetty servlet engine and HTTP server

  • Java SE Runtime Environment 8 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 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, click the Global Settings link in the Administration menu. If your free update period has expired, you need to extend your subscription.

  • Verify that your current YouTrack installation is version 7.0 or later. The current version of your installation is shown at the bottom of any page in the application. If your current installation is earlier than 7.0, you must upgrade to version 7.x first, then upgrade to YouTrack 2017.2.

Upgrade an MSI Installation

If your YouTrack Standalone service was previously installed using an MSI distribution, you can use the MSI distribution to upgrade to the latest version of YouTrack Standalone.

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:

  1. Download the MSI distribution from the the JetBrains website.

  2. Open the Windows Installer Package (MSI file).

    • The JetBrains YouTrack Setup Wizard opens.

    youtrack setup wizard upgrade
  3. 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.

      upgrade setup wizard complete

  4. Click the Finish button to close the setup wizard.

  5. 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 Standalone database in a different location or want to use the location of another YouTrack Standalone installation as the upgrade source.

    • Discard the detected settings and perform a clean installation.

    ConfigurationWizardMSI 7 0 thumbnail

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

  7. On the Confirm Settings page, confirm the basic system settings.

    Setting

    Description

    Base URL

    The URL where end users access YouTrack Standalone.

    Application Listen Port

    The port your YouTrack Standalone server listens to after installation.

    Application Listen Address

    The IP address that your YouTrack Standalone listens to after installation.

    Data Directory Location

    The directory where YouTrack Standalone stores content data.

    Backup Location

    The directory where YouTrack Standalone stores backups of the database.

    Logs Location

    The directory where YouTrack Standalone stores log files.

    Temp Location

    The directory where YouTrack Standalone stores product-specific temporary files.

    To change the location for any of these file types, click the Change button and select a new location.

  8. When done, click Upgrade.
    • The configuration is applied to your YouTrack Standalone server.

      Do not close the page in the browser until the setup is complete.

    • When the YouTrack Standalone server is ready, the Dashboard opens. Your YouTrack Standalone instance is upgraded and ready for use.

Upgrade a non-MSI Installation with an MSI Distribution

You can upgrade an existing installation that was installed with a ZIP 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:

  1. Download the MSI distribution from the JetBrains website.

  2. Stop the YouTrack service. For specific instructions, see Stop and Start YouTrack.

  3. 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, kill the outstanding process trees.

  4. Clear out your <youtrack_home> directory.

    • For a ZIP installation, the <youtrack_home> directory is the location where the ZIP distribution was unpacked during installation.

    We recommend that you perform the following steps:

    • Rename the existing <youtrack_home> directory to YouTrack_old (you can use another name).

    • Create a new <youtrack_home> directory in the same location as the previous installation.

  5. Open the Windows Installer Package (MSI file).

    • The JetBrains YouTrack Setup Wizard opens.

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

  7. In the Configuration Wizard, click Upgrade.

  8. On the Select Upgrade Source page, click the Select button and select an upgrade source.

    • Select the location of the previous ZIP installation as the upgrade source.
      or

    • Select the location where a backup copy of your database is stored as a ZIP file or unzipped backup.

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

  10. When done, click Next.

  11. Continue from step 6 of the upgrade procedure as described for the MSI Installation.

Troubleshooting

If you encountered a problem and the installation failed, see if any of the following conditions apply.

Condition

The upgrade to YouTrack 2017.2 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

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

  2. Review the contents of the install.txt log file. The failure report begins with the string Return value 3.

  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

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

  1. Check the log files, particularly service.log, for errors. The default location of the log files is %programdata%\JetBrains\YouTrack\logs

  2. 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 Restore an Installation.

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

  1. Log in to the previous version of YouTrack and create a backup of your database.

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

  3. Perform a clean installation of YouTrack 2017.2. Select the option to remove the previous configuration.

  4. In the Configuration Wizard, select the backup of the previous version as the upgrade source.

Report a Problem with the Upgrade Installation

If you continue to experience problems with the upgrade installation:

  1. Create an issue in the YouTrack project.

  2. 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: 7 March 2019
Upgrade with a ZIP DistributionUpgrade with a JAR Distribution

See Also

Installation and Upgrade: