Configure Built-in TLS in Web-based Configuration Wizard
YouTrack allows you to secure the network connection with a built-in TLS. You can enable HTTPS mode either in the Configuration Wizard or from the command line. But no matter which method you prefer, this procedure does not depend on the distribution type that you use. Thus, the procedures are described separately from the basic ones.
This page describes steps to enable HTTPS in the Configuration wizard. For the detailed instructions for the command line, see Configure Built-in TLS from the Command Line.
A summarized procedure for enabling the built-in TLS in Configuration Wizard looks as follows:
If you have a running YouTrack service, stop it.
Start an installation or an upgrade.
In the web-based Configuration Wizard, enable and configure HTTPS settings.
Complete installation or upgrade.
Enjoy running your YouTrack server over HTTPS.
Let's see the procedures in more details.
Enable HTTPS during Installation
To enable HTTPS during a clean installation
Prepare a compliant server private key and certificate or a keystore.
Start installation.
When the web-based Configuration Wizard opens, click the Set up link.
In the Server settings page, click the HTTPS tab to enable the TLS settings. The port and the base URL are corrected automatically.
Optionally, enable Redirect from HTTP to HTTPS. This option enables a non-secure port that receives all HTTP requests and redirects them to the secure listen port.
Depending on whether you use a keystore or a private key and certificate, select the relevant option.
Provide the required files:
For the keystore: the keystore file, its password, the alias and its password.
For the certificate: the private key, certificate itself, and, optionally, the chain certificate, if you use one.
For more details about the TLS specific parameters, refer to the table below.
Complete the remaining steps of the Configuration Wizard to finish the installation and start the YouTrack service.
Upgrade Scenarios with Built-in TLS
When it comes to the upgrade, you have three use cases:
You want to enable the TLS on a server that previously used plain HTTP.
You have a server that is already configured to use the built-in TLS. You just want to get a newer version of the application.
You have a server that is already configured to use the built-in TLS. However, you want to use another certificate or a keystore for the server. The reason might be an expiring certificate in the existing database, or, for example, you wish to switch to a production environment and stop using a self-signed existing certificate. What ever the reason is, you can upload a new certificate or a keystore during the upgrade in the web-based Configuration wizard.
Switch From HTTP to HTTPS During Upgrade
If your previous version used the plain HTTP connection, then the steps to enable and configure the built-in TLS are quite similar to those during the clean installation.
To enable HTTPS during an upgrade:
Stop the currently running YouTrack service.
Start a newer installation package or a docker image.
On the start page of the Configuration Wizard, click Upgrade.
Select the upgrade source.
Click HTTPS tab to configure TLS.
Optionally, enable Redirect from HTTP to HTTPS. This option enables a non-secure port that receives all HTTP requests and redirects them to the secure listen port.
Depending on whether you use a keystore or a private key and certificate, select the relevant option.
Provide the required files:
For the keystore: the keystore file, its password, the alias and its password.
For the certificate: the private key, certificate itself, and, optionally, the chain certificate, if you use one.
For more details about the TLS specific parameters, refer to the TLS-specific Attributes.
Review other settings, and adjust if required.
When done, click Upgrade to finish upgrading YouTrack service.
Upgrade an Existing Server with Enabled TLS and Valid Certificate
If the built-in TLS was enabled in your previous installation and the server certificate or keystore is still valid, then you can safely reuse them during the upgrade.
To upgrade an existing service with already enabled built-in TLS:
Stop the currently running YouTrack service.
Start a newer installation package or a docker image.
On the start page of the Configuration Wizard, click Upgrade.
Select the upgrade source.
Click HTTPS tab to configure TLS.
Optionally, enable Redirect from HTTP to HTTPS.
If the source database contains the valid server certificate, the option Use existing files is enabled by default. The validity date of the found server certificate is provided next to this option.
Review other settings, and adjust if required.
When done, click Upgrade to finish upgrading YouTrack service.
Apply a New TLS Certificate or Keystore during Upgrade
If built-in TLS was enabled for your installation but the server certificate or keystore is invalid or expiring, you can upload a new one during upgrade.
To enable HTTPS during upgrade:
Stop the YouTrack service.
Run a newer installation package or Docker image.
>When the Configuration Wizard launches, click the Upgrade link.
Select the upgrade source.
During the Confirm Settings step, switch to the HTTPS configuration.
Optionally, enable the Redirect from HTTP to HTTPS option. This enables a non-secure port that receives all HTTP requests and redirects them to the secure listen port.
For the Server Certificate setting, select the Upload new TLS certificate option. Depending on whether you use a keystore or a private key and certificate, select the relevant option.
Provide the required files:
For a keystore: the keystore file, its password, the alias and its password.
For a certificate: the private key, certificate itself, and, optionally, the chain certificate, if you use one.
For details, see TLS Settings.
Review other settings, and adjust if required.
When done, click Upgrade and finish upgrading the YouTrack service.
TLS Settings
Setting | Description |
|---|---|
Redirect from HTTP to HTTPS | Option that lets you to enable and configure a non-secure port to redirect all HTTP requests to the newly configured HTTPS secure port. |
Keystore | |
Keystore file | A keystore is a JKS or PKCS #12 file that contains a certificate and a private key that secure your HTTPS connection. |
Password | The password that protects the keystore file. |
Alias | The alias (known as the "friendly name" for PKCS #12) of the entry in the keystore that contains the server certificate and the private key. If you use a PKCS #12 keystore, and the private key and certificate pair is not marked with a friendly name during generation, enter the sequential number of this pair in the keystore as the Alias. If the keystore contains only one pair of private key and certificate, then enter |
Alias password | The password that was used to encrypt the private key. If the private key is not encrypted, leave the field blank. This field is optional. When left blank, the configuration wizard first checks whether the keystore password is used as the alias password. If this doesn't match, the wizard tries again using an empty value. If neither of these values is a match, an error message informs you that the alias password is incorrect. |
Private key and certificate | |
Private key | The private key PEM file that secures and verifies connections using your server certificate. |
Certificate | Server certificate PEM file that secures the HTTPS connection to your domain. |
Certificate chain | The chain of intermediate certificates between your server certificate and the root certificate. |
To learn how to generate a private key and certificate, see TLS Server Certificates and Keystores.