YouTrack Server 2022.3 Help

Update the URL for your Hub Server

To connect to an external Hub service, YouTrack needs to know where to look for it. The location of the external Hub service is stored in YouTrack's configuration files. To prevent accidental edits, this setting is not exposed in the administrative UI. To update this URL, you can either use the Hub migration service or update the value that is stored in a property file on the YouTrack server.

There are a few situations where you need to update the URL for an external Hub server in YouTrack.

  • The external Hub installation was reconfigured and its base URL has changed.

  • The external Hub installation was corrupted and restored to another location with a different base URL.

  • A new copy of Hub was installed in a different location and you want YouTrack to connect to the new installation. The base URL of the new installation differs from the base URL of the old installation.

There are two methods that you can use to update the Hub URL in YouTrack.

Registering YouTrack as a Service in the New Hub Installation

If you're switching to a new installation, YouTrack must already be registered as a service in this Hub installation. Otherwise, YouTrack won't start. This condition is satisfied when:

  • The database for the new Hub installation was restored from a backup file that belonged to the Hub installation that was previously used by YouTrack.

  • The new Hub installation was created by migrating the previous Hub installation to the new installation.

  • The YouTrack service has been added manually to the registry for the new Hub installation. For a detailed description of this procedure, refer to the Hub documentation.

Before you attempt to update the URL for your Hub server in YouTrack, verify that YouTrack is properly registered in the new Hub installation. For more information, refer to the Hub documentation.

Updating the Hub URL with the Hub Migration Service

If your YouTrack service is running, you can update this property using the Hub migration service that is built into YouTrack. This method is only available when the Hub service is still available from the previous URL.

This method is preferable because it validates whether the external Hub service is available from the new URL and verifies that the YouTrack service is registered in Hub.

If the certificate that secures connections to the Hub server is self-signed or not issued by a known Certificate Authority, it is automatically imported into the internal trust store for YouTrack.

To update the Hub URL in the migration service:

  1. Enter the URL for the migration service in the address bar in your web browser. The URL is the base URL for your YouTrack installation appended with /bundle/admin.

    • The login page for the Hub migration service opens.

  2. Log in to the migration service.

    To log in to the migration service, you need to prove that you are a system administrator and have access to the file system of the server where the application is installed. To confirm your access rights, the migration service asks for a token that is located on the application server.

    1. Click the Show token location link.

    2. Open the awcToken.properties file that is stored on the server.

    3. Paste the token from the file into the Token field.

    4. Click the Log in button.

  3. Enter the new base URL of the external Hub server.

  4. Click the Verify URL button.

  5. Click the Accept button to confirm the request access to the external Hub service.

  6. Review and resolve conflicts (if any were found) and confirm that the Hub service is accessible from its new location.

    • The YouTrack service is updated to connect to the Hub service using the new URL.

Updating the Hub URL Manually

If YouTrack has shut down because it can no longer connect to the Hub service, you can update the Hub URL manually. This operation is performed by applying a command to the YouTrack server. For MSI installations, you must run this command as an administrator.

If the certificate that secures connections to the Hub server is self-signed or not issued by a known Certificate Authority, you need to import the certificate into the internal keystore for YouTrack as well. For detailed instructions, see Update the Certificate for Your Hub Server.

To update the Hub URL manually:

  1. Open a command-line interface and enter the following command:

    docker run -it -v /path/to/conf/on/host:/opt/youtrack/conf -v ... <YT_MAGE_ID> configure --hub-url=<url-with-/hub-at-the-end>

  2. For <url-with-/hub-at-the-end>, specify the base URL for your new Hub installation and append it with /hub.

  3. Start YouTrack.

    • YouTrack connects to the Hub service using the new URL.

To update the Hub URL manually:

  1. Open a command-line interface and enter the following command:

    java -jar /path/to/youtrack.jar configure <YT_MAGE_ID> configure --hub-url=<url-with-/hub-at-the-end>

  2. For <url-with-/hub-at-the-end>, specify the base URL for your new Hub installation and append it with /hub.

  3. Start YouTrack.

    • YouTrack connects to the Hub service using the new URL.

To update the Hub URL manually:

  1. Use one of the following methods to update the values in the bundle.properties file:

    • Open a command-line interface on the YouTrack server and enter the following command:

      <youtrack_home>/bin/youtrack.sh configure --hub-url=<url-with-/hub-at-the-end>

    • Open the <youtrack_app_data>/conf/internal/bundle.properties file and manually change the values for the following properties:

      hub-url=<url-with-/hub-at-the-end>

  2. For <url-with-/hub-at-the-end>, specify the base URL for your new Hub installation and append it with /hub.

  3. Start YouTrack.

    • YouTrack connects to the Hub service using the new URL.

To update the Hub URL manually:

  1. Use one of the following methods to update the values in the bundle.properties file:

    • Open a command-line interface on the YouTrack server and enter the following command:

      <youtrack_home>\bin\youtrack.bat configure --hub-url=<url-with-/hub-at-the-end>

    • Open the <youtrack_app_data>\conf\internal\bundle.properties file and manually change the values for the following properties:

      hub-url=<url-with-/hub-at-the-end>

  2. For <url-with-/hub-at-the-end>, specify the base URL for your new Hub installation and append it with /hub.

  3. Start YouTrack.

    • YouTrack connects to the Hub service using the new URL.

Last modified: 13 April 2021
Migrate YouTrack Data to External Hub Update the Certificate for Your Hub Server