YouTrack Server 2022.3 Help

Upgrade with a JAR Distribution

This page describes how to upgrade an existing YouTrack installation using the YouTrack JAR distribution.

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.

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

The current version number for a YouTrack Server installation.

Upgrade an Existing JAR Installation

If you run YouTrack as a standalone Java process with the JAR distribution, the upgrade procedure is quite straightforward.

To upgrade YouTrack with the JAR distribution:

  1. Download the JAR distribution.

  2. Create a backup of your current database.

  3. Stop the YouTrack server.

  4. In a command-line interface, enter a command to start the upgrade:

    java -jar youtrack-<version>.jar

    If you run the application with a script, deploy the new JAR file and start the server.

    Make sure to run the new JAR file with the same user account that you used for the previous version.

    For details about running YouTrack JAR, see Run YouTrack JAR.

    • The web-based Configuration Wizard starts.

    • If you have a browser installed on the host machine, the Configuration Wizard opens automatically.

    • If you do not have a web browser installed on the host machine, open the URL of the wizard in a web browser on another workstation. The wizard URL is printed in the console output:

      JetBrains YouTrack <version> will be available on [<YouTrack Base URL>/bundle/starting?wizard_token=<value>] after start

    The installation script automatically detects that there is an older version of the application installed on the server and opens directly to the page that lets you upgrade using settings from the previous installation.

  5. On the Confirm Settings page, confirm or change your system settings and the location of system directories.

    YouTrack JAR upgrade settings

    Here you can also enable built-in TLS to secure the network connection for the server. If you want to apply this change during an upgrade installation, follow the instructions for switching to HTTPS during upgrade, starting from the step that tells you to switch to HTTPS.

  6. When done, click Next.

  7. Review your license. If required, you can also update your license on this page.

    Review your license
  8. When done, click Finish.

    • YouTrack launches the components that support the application.

      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.

If you experience a problem during the upgrade, please create an issue. Describe the problem and attach your logs to the issue. Restore the previous YouTrack version with the pre-upgrade database backup.

Upgrade a non-JAR Installation with JAR

This section describes how you can upgrade your existing non-JAR YouTrack installation using the JAR distribution.

To upgrade an existing YouTrack installation:

  1. Download the JAR distribution.

  2. Create and download a fresh backup of your current database.

  3. Stop the YouTrack service.

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

  5. In a command-line interface, enter a command to start the upgrade:

    java -jar youtrack-<version>.jar

    For details about running YouTrack JAR, see Run YouTrack JAR.

    • The web-based Configuration Wizard starts.

  6. Open the web-based Configuration Wizard.

    • If you have a browser installed on the host machine, the Configuration Wizard opens automatically.

    • If you do not have a web browser installed on the host machine, open the URL of the wizard in a web browser on another workstation. The wizard URL is printed in the console output:

      JetBrains YouTrack <version> will be available on [<YouTrack Base URL>/bundle/starting?wizard_token=<value>] after start
  7. In the Configuration Wizard, click Upgrade.

    Upgrade: Configuration Wizard start page
  8. On the Select Upgrade Source page, click the Select button and select the backup file of your current database that you have created.

    Select an upgrade source
  9. When done, click Next.

  10. On the Confirm Settings page, confirm or change your system settings and the location of system directories.

    YouTrack JAR upgrade settings

    Here you can also enable built-in TLS to secure the network connection for the server. If you want to apply this change during an upgrade installation, follow the instructions for switching to HTTPS during upgrade, starting from the step that tells you to switch to HTTPS.

  11. Review your license. If required, you can also update your license on this page.

    Review your license
  12. When done, click Finish.

    • YouTrack launches its components.

      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.

Last modified: 21 April 2023