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.
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.
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.
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.
Upgrade an Existing Server with a New Certificate or Keystore
If the built-in TLS was enabled in your previous installation but the server certificate or keystore is invalid or expiring, then you can upload a new one during the upgrade.
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.
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.
TLS Specific Attributes
Attribute | 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 | Alias (Friendlyname in 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 pair of the private key and certificate is not marked with a Friendlyname during generation, then in the Alias field, you need to provide the sequential number of this pair in the keystore. 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. |
| 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. |
For more information about obtaining the private key and certificate, see TLS Server Certificates and Keystores.