YouTrack Server
 
2019.2
Get YouTrack Standalone
You are viewing the documentation for an earlier version of YouTrack Server. View this page in the current documentation
  1. Installation and Upgrade
  2. Working with External Hub
  3. Update the URL for your Hub Server

Update the URL for your Hub Server

Last modified: 17 December 2019

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.

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.

warning

Two-factor authentication

The Hub migration service uses an application token for authentication. The service doesn't support two-factor authentication.

If you need to use the migration service to update the Hub URL, disable 2FA for the account that you use to log in to the migration service. Once the update is complete, you can re-enable 2FA for your account.

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.

    • Click the Show token location link.

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

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

    • 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 the migration.

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

note

The command shown here is written for Linux and macOS. For Windows operating systems, replace .sh with .bat and use the backslash.

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.