Reverse Proxy Configuration
You can set up YouTrack to work behind a reverse proxy server.
The process that you use to enable this setup consists of the following steps:
- Configure YouTrack to point to the base URL of the proxy server.
- Configure the headers of your proxy server. This page includes guidelines for Apache, IIS, and Nginx servers and the Pound reverse proxy.
Change the Base URL of your YouTrack Server
You can use the following procedure to change the base URL for both ZIP and MSI distributions.
To execute these commands in an MSI distribution, open the Command Prompt window as an administrator.
Always execute the configure
command on behalf of the OS user that runs the YouTrack service.
This command creates configuration files and folders. The YouTrack service user should have sufficient permissions to access these files and folders.
To change the base URL for a ZIP or MSI distribution:
- Stop the YouTrack service. For specific instructions, see Stop and Start YouTrack.
- In a command-line interface, change the directory to
<youtrack_home>/bin/
. - Enter the following command:
youtrack.sh configure --listen-port 1111 --base-url http://youtrack.mydomain.com:2222
- Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, Nginx server, or Pound reverse proxy.
- Start the YouTrack service. For specific instructions, see Stop and Start YouTrack.
To change the base URL for a JAR distribution:
- Stop the YouTrack service.
- Modify the command that you use to launch the service to reference the new base URL:
java -Xmx1g -XX:MaxMetaspaceSize=256m -Djetbrains.youtrack.baseUrl=http://youtrack.mydomain.com:2222 -jar youtrack-xx.jar 1111
- Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, Nginx server, or Pound reverse proxy.
- Start the YouTrack service.
Configure Proxy Server Headers
To configure the headers in your proxy server, follow the guidelines that are specific to your server. Configuration guidelines for Apache HTTP Server, IIS, Nginx, and Pound are provided below.
Apache HTTP Server Configuration
To use an Apache HTTP Server as a reverse proxy, you need to run an a2enmod
script and add directives to a .conf
file on your server.
To set up an Apache HTTP Server as a reverse proxy:
- Use the following
a2enmod
script to enableproxy_http
,rewrite modules
(and optionallyheaders
if you want to use SSL):$ a2enmod headers $ a2enmod rewrite $ a2enmod proxy_http
- Add the following directives to the
VirtualHost
section of a relevant.conf
file:RewriteEngine on AllowEncodedSlashes on ProxyRequests off ProxyPass / http://127.0.0.1:1111/ ProxyPassReverse / http://127.0.0.1:1111/
Replace
1111
with the actual port number that your YouTrack server listens to. - To use SSL, add the following directives to the
VirtualHost
section:RequestHeader set X-Forwarded-Proto "https"
For more information, refer to the Apache mod_proxy configuration reference.
IIS Server Configuration
To use an IIS server as a reverse proxy, you need to use the Application Request Routing (ARR) extension.
To set up an IIS server as a reverse proxy:
- Download and install the Application Request Routing (ARR) extension from the Microsoft website.
- In IIS Manager, connect to the IIS server - in this case,
localhost
. - Highlight the server in the Connections pane.
- Double-click URL Rewrite.
- Click View server variables in the right pane.
- Add the following server variables to the list:
HTTP_X_FORWARDED_HOST HTTP_X_FORWARDED_SCHEME HTTP_X_FORWARDED_PROTO
- Highlight the server in the Connections pane.
- Double-click Application Request Routing Cache.
- Click Server Proxy Settings under the Proxy heading in the Actions pane.
- Select the Enable proxy checkbox, set the Response buffer threshold to
0
, then click Apply. Leave the default values in place. - Deselect the Reverse rewrite host in response headers checkbox and click Apply.
- In the Connections pane, under Sites, select Default Web Site.
- Double-click the URL Rewrite feature, then click Add Rule(s) in the Actions pane.
- Add a reverse proxy rule with the server name:
localhost:1111
(replace with the real location and port of your YouTrack service). - Open the rule, check the rewrite URL, and add the following server variables:
- Set the
HTTP_X_FORWARDED_HOST
variable to{HTTP_HOST}
. - Set the
HTTP_X_FORWARDED_SCHEME
variable tohttps
(if the IIS site is configured to use HTTPS, otherwise set the variable tohttp
). - Set the
HTTP_X_FORWARDED_PROTO
tohttps
(if the IIS site is configured to use HTTPS, otherwise set the variable tohttp
).
- Set the
- Make sure that anonymous authentication is enabled:
- In the Connections pane, under Sites, select Default Web Site.
- Double-click the Request Filtering feature, then click Edit Feature Settings in the Actions pane.
- Increase the values for the following parameters:
Parameter Value Maximum URL length 6144 Maximum query string 4096 - (Optional) To access YouTrack over HTTPS, add a new SSL binding to the Default Web Site.
Nginx Server Configuration
Use the following guidelines to configure an Nginx server as a reverse proxy. The Nginx documentation provides a description of the server_name, proxy_set_header, and proxy_pass variables.
The following example shows you how to configure Nginx headers without SSL:
server {
listen 2222;
server_name localhost;
location / {
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 10m;
proxy_http_version 1.1;
proxy_pass http://youtrackmachine.domain.local:1111;
}
location /api/eventSourceBus {
proxy_cache off;
proxy_buffering off;
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
proxy_set_header Connection '';
chunked_transfer_encoding off;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_pass http://youtrackmachine.domain.local:1111;
}
}
Set the following variables to match your YouTrack configuration:
listen 2222
is the port number that you specified in the--base-url
parameter.-
proxy_pass http://youtrackmachine.domain.local:1111
is the path to your YouTrack server with the port that you specified with the-–listen-port
command.
The client_max_body_size
directive defines the maximum amount of data that Nginx accepts in an HTTP request.
If you don't specify a value, the default set by Nginx is 1 megabyte.
We recommend that you increase the maximum to 10 megabytes to correspond to the default value in YouTrack.
The second location
block disables buffering for connections from the agile board to support live updates.
If you customize any of the common connection settings in the first location
block, you should set the same custom parameters for the /api/eventSourceBus
location.
You can also put all of your common settings in a separate file and reference the file with an include
directive.
For more information, read the Nginx documentation.
The following example shows you how to configure Nginx headers with SSL:
server {
listen 443 ssl;
ssl_certificate <path_to_certificate>
ssl_certificate_key <path_to_key>
server_name localhost;
location / {
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 10m;
proxy_http_version 1.1;
proxy_pass http://youtrackmachine.domain.local:1111;
}
location /api/eventSourceBus {
proxy_cache off;
proxy_buffering off;
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
proxy_set_header Connection '';
chunked_transfer_encoding off;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_pass http://youtrackmachine.domain.local:1111;
}
}
Again, customize common connection settings in both location
blocks, or store common settings in a separate file and reference the file with an include
directive.
For more information, read the Nginx documentation.
If you use a Java KeyStore, you need to convert it to the PKCS12 format to use a Nginx server as an SSL-terminating proxy. The following procedure shows you how to convert the keystore using keytool and openssl.
To convert a Java KeyStore to PKCS12 format:
- Use keytool to convert your current
.jks
file to the PKCS12 key store format.p12
:keytool -importkeystore -srckeystore oldkeystore.jks -destkeystore newkeystore.p12 -deststoretype PKCS12 Enter destination keystore password: [enter private key password from oldkeystore.jks, it will be password for newkeystore.p12] Re-enter new password: [same as above] Enter source keystore password: [enter password for oldkeystore.jks] ... Enter key password for <key alias name> [enter private key password from oldkeystore.jks] ...
You will be required to enter a "destination keystore password". If your
.jks
keystore contains a private key with a password, then the "destination keystore password" should equal the password of the private key. - List the contents of the new key store file:
keytool -deststoretype PKCS12 -keystore newkeystore.p12 -list Enter keystore password: [enter password for newkeystore.p12 provided on step 1] ...
- Extract the .pem file (certificate) from the
.p12
key store:openssl pkcs12 -nokeys -in newkeystore.p12 -out certfile.pem Enter Import Password: [enter password for newkeystore.p12 provided on step 1] ...
- Extract the unencrypted key file from the
.p12
key store:openssl pkcs12 -nocerts -nodes -in newkeystore.p12 -out keyfile.key Enter Import Password: [enter password for newkeystore.p12 provided on step 1] ...
Pound Reverse Proxy Configuration
The following example shows you how to configure a Pound reverse proxy with SSL.
This configuration is set in the /etc/pound/pound.cfg
file.
## global options:
User "www-data"
Group "www-data"
## Logging: (goes to syslog by default)
LogLevel 1
## check backend every X secs:
Alive 30
# poundctl control socket
Control "/var/run/pound/poundctl.socket"
## forward all requests from HTTPS 0.0.0.0:8443 to HTTP youtrackmachine.domain.local:8080:
ListenHTTPS
Address 0.0.0.0
Port 8443
Cert "/home/user/cert.pem"
AddHeader "X-Forwarded-Proto: https"
## allow PUT and DELETE
xHTTP 1
Service
BackEnd
Address youtrackmachine.domain.local
Port 8080
End
End
End
CORS Support
If you use an external Hub service, YouTrack may require CORS support to make calls to Hub. The aforementioned configurations work fine and don't require any further tuning. Additional custom proxy rules, however, may interfere with CORS, making login to YouTrack impossible.
Consider the following guidelines when using an external Hub service behind the reverse proxy:
- Proxy rules should not block CORS-related HTTP headers:
- The proxy server should allow HTTP OPTIONS requests.
- HTTP OPTIONS requests should not be a subject of proxy-enforced authentication, if any. For example, you may want to set up certificate-based authentication to comply with enterprise security policy. In this case, an authentication check should be skipped if incoming request is an OPTIONS type. OPTIONS requests cannot return any customer-related data by themselves, so it's safe to let them in.
Troubleshooting
If users report problems working with YouTrack behind a reverse proxy server, check the following errors.