YouTrack Server 2022.3 Help

Upgrade with Docker Container

This page describes various scenarios of upgrading an existing YouTrack service using the YouTrack docker image.

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 a Docker Image

  1. Create a backup of the YouTrack database while your existing YouTrack installation is running.

  2. Stop the running YouTrack docker container:

    docker exec <CONTAINER_ID> stop
  3. Remove the container with the previous version.

    docker rm <CONTAINER_ID>

    Otherwise, when you run the new version of the container, the command will fail because of the container names conflicts.

  4. Pull an image of the latest YouTrack version from the Docker YouTrack Repository:

    docker pull jetbrains/youtrack:<version>

    Replace <version> with the complete version number and build. For a complete list of release versions, check Docker Hub.

  5. Execute the following command to run a container with the new YouTrack version, that you have pulled from the repository. All other attributes of the command (volumes and port mappings) must be the same as you have used to run the previous version of the YouTrack image:

    docker run -it --name <arbitrary-youtrack-container-name> \ -v <path to data directory>:/opt/youtrack/data \ -v <path to conf directory>:/opt/youtrack/conf \ -v <path to logs directory>:/opt/youtrack/logs \ -v <path to backups directory>:/opt/youtrack/backups \ -p <port on host>:8080 \ jetbrains/youtrack:<new version>
    • In the console output, an URL to the web-based Configuration Wizard is provided.

  6. In a browser, open the web-based Configuration Wizard by the URL.

  7. Review the upgrade settings. Click Next.

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

    Review your license
  9. When done, click Upgrade.

    • YouTrack Server launches its components.

      Do not close the page in the browser until the setup is complete. When the YouTrack Server server is ready, you are redirected to the login page.

  10. Enter the credentials for the YouTrack Server administrator account and click the Log in button.

    • YouTrack opens to the Dashboard page.

    Your YouTrack Server installation is upgraded and ready to use.

Upgrade an Existing Installation from a Database Backup using a Docker Image

You also have the ability to upgrade any installation type using a docker image by downloading a backup copy of your YouTrack database and using the backup as the upgrade source in the configuration wizard during installation of the latest version.

This procedure can be used to upgrade any installation type (JAR, MSI, or ZIP). It can also be used to migrate an installation from one Docker container to another during the upgrade process.

  1. Create a backup of the YouTrack database while your existing YouTrack installation is running.

  2. Stop the existing YouTrack service.

  3. Pull an image of the latest YouTrack version from the Docker YouTrack Repository:

    docker pull jetbrains/youtrack:<version>

    Replace <version> with the complete version number and build. For a complete list of release versions, check Docker Hub.

  4. Create and configure YouTrack-specific directories on the host machine.

  5. Copy the backup file of the YouTrack database into the backups directory, that you created in the previous step.

  6. Run the container with YouTrack server and map YouTrack data volumes and port.

    • YouTrack service starts with the web-based Configuration Wizard. The URL at which you can access the wizard is displayed in the command output.

  7. In a browser, open the URL to access the wizard.

  8. In the Configuration Wizard, click Upgrade.

    Configuration wizard starts
  9. On the Select Upgrade Source page, click the Select button and select the backup file as an upgrade source.

    Select a source for upgrade

    Click Next.

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

    Docker upgrade confirm settings
  11. Review your license. If required, you can also update your license on this page.

  12. When done, click Upgrade.

    • YouTrack Server launches its components.

      Do not close the page in the browser until the setup is complete. When the YouTrack Server server is ready, you are redirected to the login page.

  13. Enter the credentials for the YouTrack Server administrator account and click the Log in button.

    • YouTrack opens to the Dashboard page.

    Your YouTrack Server installation is upgraded and ready to use.

Last modified: 22 November 2022