YouTrack Server 2022.3 Help

Reverse Proxy Configuration

You can set up YouTrack to work behind a reverse proxy server.

The reverse proxy setup consists of the following steps:

  1. Configure YouTrack to point to the base URL of the proxy server.

  2. Configure the headers of your proxy server. This page includes guidelines for Apache, IIS, and NGINX servers.

Prerequisites

To get the best performance from your YouTrack installation, your proxy server should support HTTP/2. For most servers, the HTTP/2 protocol only works with HTTPS connections, which means that you need to secure your connections with an SSL/TLS certificate.

You also need to ensure that the OpenSSL library that is used by the reverse proxy server is version 1.0.2 or later. With earlier versions of OpenSSL, users connect using the legacy HTTP/1.1 specification, which lacks the performance benefits of an HTTP/2 connection.

The instructions on this page assume that these requirements are met. Use the following list to determine which server version is required to complete this setup:

Server

Minimum Version

Apache

2.4.17

IIS

10.0 version 1709

NGINX

1.11.7

HTTP Strict Transport Security

We also strongly recommend that you set up your reverse proxy server to use HTTP Strict Transport Security (HSTS). This protects your installation against possible man-in-the-middle attacks, where the redirect from the HTTP to the HTTPS version of the site can be exploited to direct a user to a malicious site instead of the secure version of the original page.

The instructions for proxy server header configurations that are provided on this page include the directives that support HSTS.

Performance Optimization for Worker Connections

You will also need to optimize the performance settings for your server to allow a sufficient number of connections to YouTrack. These connections are required by pages that support live updates. If you have an insufficient number of connections, or are serving pages over plain HTTP, issues and agile boards that are opened in new tabs are either blank, loading, or partially loaded.

The exact values for connection-related directives vary based on server load. Use the diagnostic tools for your reverse proxy to determine whether you provide sufficient connections and adjust these values accordingly.

Change the Base URL of your YouTrack Server

You can change the base URL for your YouTrack server from the command line using the configure command.

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 of the YouTrack service in a Docker container:

  1. Stop YouTrack: docker exec <containerId> stop

  2. Execute the following command:

    docker run --rm -it \ -v <path to conf directory>:/opt/youtrack/conf \ jetbrains/youtrack:<version> \ configure --base-url=https://youtrack.mydomain.com:XXXX

    • https://youtrack.mydomain.com is the address of your proxy server.

    • XXXX is the port number that your proxy server listens to.

    Important! For the docker container, the application listen port inside the container is not changed. That's why it isn't mentioned in the provided command.

    Instead, you need to configure your proxy server to pass all traffic to the host port that is mapped to the application listen port inside the container. The host port is configured with -p parameter when you execute the docker run command:

    docker run -p <port-on-host-machine-that-passes-traffic-from-proxy>:8080

  3. Start YouTrack: docker start <containerId>

To change the base URL for a JAR distribution:

  1. Stop the YouTrack service.

  2. Run the configure command for the YouTrack service:

    java -jar youtrack-<version>.jar configure --listen-port 1111 --base-url https://youtrack.mydomain.com:XXXX/contextPath

    • 1111 is the port number that your YouTrack server listens to.

    • https://youtrack.mydomain.com is the address of your proxy server.

    • XXXX is the port number your proxy server listens to.

    • contextPath is the name of the subdirectory where you run your YouTrack server, if you're not serving the application from the root context.

  3. Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, or NGINX server.

  4. Start the YouTrack service.

To execute these commands in an MSI distribution, open the Command Prompt window as an administrator.

To change the base URL for an MSI distribution:

  1. Stop the YouTrack service. For specific instructions, see Stop and Start YouTrack.

  2. In a command-line interface, change the directory to <youtrack_home>\bin\.

    For an MSI installation, the <youtrack_home> directory is the location where YouTrack was installed.

  3. Enter the following command:

    youtrack.bat configure --listen-port 1111 --base-url https://youtrack.mydomain.com:XXXX/contextPath

    • 1111 is the port number that your YouTrack server listens to.

    • https://youtrack.mydomain.com is the address of your proxy server.

    • XXXX is the port number your proxy server listens to.

    • contextPath is the name of the subdirectory where you run your YouTrack server, if you're not serving the application from the root context.

  4. Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, or NGINX server.

  5. Start the YouTrack service. For specific instructions, see Stop and Start YouTrack.

To change the base URL for a ZIP distribution:

  1. Stop the YouTrack service. For specific instructions, see Stop and Start YouTrack.

  2. In a command-line interface, change the directory to <youtrack_home>/bin/.

    For a ZIP installation, the <youtrack_home> directory is the location where the ZIP distribution was unpacked during installation.

  3. Enter the following command:

    youtrack.sh configure --listen-port 1111 --base-url https://youtrack.mydomain.com:XXXX/contextPath

    • 1111 is the port number that your YouTrack server listens to.

    • https://youtrack.mydomain.com is the address of your proxy server.

    • XXXX is the port number your proxy server listens to.

    • contextPath is the name of the subdirectory where you run your YouTrack server, if you're not serving the application from the root context.

  4. Configure the headers in your proxy server. Follow the guidelines that are appropriate for your Apache, IIS, or NGINX server.

  5. Start the YouTrack service. For specific instructions, see Stop and Start YouTrack.

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.

Requires Apache httpd version 2.4.17 or later.

To set up an Apache HTTP Server as a reverse proxy:

  1. Use the following a2enmod script to enable the headers, rewrite, proxy_http, ssl, and http2 modules:

    $ a2enmod headers $ a2enmod rewrite $ a2enmod proxy_http $ a2enmod ssl $ a2enmod http2

  2. Add the following directives to the VirtualHost section of a relevant .conf file:

    Protocols h2 http/1.1 RequestHeader set X-Forwarded-Proto "https" RewriteEngine on AllowEncodedSlashes on ProxyRequests off ProxyPass / http://127.0.0.1:1111/ ProxyPassReverse / http://127.0.0.1:1111/ SSLEngine On SSLCertificateFile <path_to_certificate> SSLCertificateKeyFile <path_to_key>

  3. Set the following variables to match your YouTrack configuration:

    • Replace 1111 with the actual port number that your YouTrack server listens to.

    • Set the value for the <path_to_certificate> to the location of the SSL/TLS certificate for your server.

    • Set the value for the <path_to_key> to the location of the PEM-encoded private key file for the server certificate.

  4. Add the additional HSTS header to the HTTPS VirtualHost directive. Max-age is measured in seconds.

    # Guarantee HTTPS for 1 Year including subdomains Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"

    Note that this header is only valid on a HTTPS VirtualHost.

  5. Add a server-side redirect to upgrade non-HTTPS connections the first time the site is accessed. Add this to the non-HTTP VirtualHost.

    [...] ServerName myYouTrackService.com Redirect permanent / https://myYouTrackService.com/

    Replace myYouTrackService.com with the actual domain name of your YouTrack server.

  6. If you plan to use the remote script debugger for the scripts in your YouTrack, make the following changes to the Apache configuration. It will enable WebSockets, which are required by the debugger.

    1. Enable the proxy_wstunnel module:

      $ a2enmod proxy_wstunnel

    2. Add the following directives to the VirtualHost section of a relevant .conf file:

      RewriteEngine On RewriteCond %{HTTP:Connection} Upgrade [NC] RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteRule ^/debug(.*)$ ws://127.0.0.1:1111/debug$1 [P,L]

For more information, refer to the documentation for the Apache Module mod_proxy.

IIS Server Configuration

To use an IIS server as a reverse proxy, you need to use the Application Request Routing (ARR) extension.

Requires IIS version 10.0 version 1709 or later.

To set up an IIS server as a reverse proxy:

  1. Download and install the Application Request Routing (ARR) extension from the Microsoft website.

  2. In IIS Manager, connect to the IIS server - in this case, localhost.

  3. Highlight the server in the Connections pane.

  4. Double-click URL Rewrite.

  5. Click View server variables in the right pane.

  6. Add the following server variables to the list:

    HTTP_X_FORWARDED_HOST HTTP_X_FORWARDED_SCHEME HTTP_X_FORWARDED_PROTO

  7. Set the response buffer threshold. For single web servers:

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

    For server farms:

    • Select the YouTrack server farm in the Connections pane.

    • Double-click the Proxy icon.

    • In the Buffer Setting section of the form, set the Response buffer threshold to 0, then click Apply.

  8. Deselect the Reverse rewrite host in response headers checkbox and click Apply.

  9. In the Connections pane, under Sites, select Default Web Site.

  10. Double-click the URL Rewrite feature, then click Add Rule(s) in the Actions pane.

  11. Add a reverse proxy rule with the server name: localhost:1111 (replace with the real location and port of your YouTrack service).

  12. 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 to https.

    • Set the HTTP_X_FORWARDED_PROTO to https.

  13. Make sure that anonymous authentication is enabled:

    • In the Sites section of the Connections pane, select Default Web Site.

    • Double-click Authentication, select Anonymous, then click Enable in the right pane.

  14. Make sure that Dynamic Content Compression is disabled. The location of this setting varies by operating system.

  15. In the Connections pane, under Sites, select Default Web Site.

  16. Double-click the Request Filtering feature, then click Edit Feature Settings in the Actions pane.

  17. Increase the values for the following parameters:

    Parameter

    Value

    Maximum URL length

    10000

    Maximum query string

    10000

    If you update these properties directly in the web.config file, it should look something like this:

    <system.web> <httpRuntime maxUrlLength="10000" maxQueryStringLength="10000" /> </system.web>

  18. Add a new SSL binding to the Default Web Site.

    • The address that the SSL binding listens to (Host URL) should match the YouTrack base URL.

    • The certificate that you choose should correspond to the server DNS address.

  19. Configure the HTTP Strict Transport Security (HSTS) settings for the Default Web Site

    • Set the enabled attribute for the <hsts> to true.

    • Specify a value for the max-age attribute. For example, 31536000 (one year, in seconds).

    • Set the values for the includeSubDomains and redirectHttpToHttps to true as well.

    For specific instructions, please refer to the IIS configuration reference.

  20. If you plan to use the remote script debugger for the scripts in your YouTrack, make the following changes to the IIS configuration. It will enable WebSockets, which are required by the debugger.

    1. Make sure your IIS server supports WebSockets. For instructions how to install the WebSockets support module for an IIS server, refer to the IIS documentation.

    2. Add the following variable to the list of server variables:

      HTTP_SEC_WEBSOCKET_EXTENSIONS

    3. In your reverse proxy rule, set the HTTP_SEC_WEBSOCKET_EXTENSIONS variable to client-max-window-bits.

NGINX Server Configuration

The basic requirements for configuring an NGINX server as a reverse proxy consist of the following steps:

Requires NGINX version 1.11.7 or later.

To configure NGINX reverse proxy headers:

  1. Open the configuration file for your NGINX server. By default, the configuration file is named nginx.conf. The default directory is either /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx.

    You can find the exact location of the configuration file by entering nginx -V in a command line interface.

  2. Increase the value for the worker_rlimit_nofile directive to a minimum value of 4096.

  3. In the events section, increase the value for the worker_connections directive to a minimum value of 2048.

  4. Update the server directive and add the proxy_set_header and proxy_pass directives in your configuration file.

    Use the following sample as a guide:

    server { listen 443 ssl http2; ssl_certificate <path_to_certificate>; ssl_certificate_key <path_to_key>; server_name localhost; add_header Strict-Transport-Security max-age=31536000; location /contextPath/ { 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_buffers 8 64k; proxy_busy_buffers_size 128k; proxy_buffer_size 64k; client_max_body_size 10m; proxy_http_version 1.1; proxy_pass http://youtrackmachine.domain.local:1111/contextPath; } location /contextPath/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/contextPath/api/eventSourceBus; } }

    For best results, use the recommended values for proxy_buffers, proxy_busy_buffers_size and proxy_buffer_size as provided in this sample. This configuration helps avoid gateway errors when users upload large files to your YouTrack server. Pay specific attention to the recommended value for the proxy_buffers directive, as the default values are usually too small to accommodate the 64k buffer.

    You should also double-check the value for the proxy_pass directive and remove any trailing slash characters from the web address. Failure to format the address correctly leads to problems with live updates.

  5. Set the following variables to match your YouTrack configuration:

    • listen 443 is the port number that you specified in the --base-url parameter.

    • proxy_pass http://youtrackmachine.domain.local:1111/contextPath is the path to your YouTrack server with the port that you specified with the -–listen-port command.

    • contextPath is the name of the subdirectory where you run YouTrack.

      If you're running YouTrack from the default (root) context, remove this reference and the slash that precedes it from your configuration file.

  6. If you plan to use the remote script debugger for the scripts in your YouTrack, add the following block to your configuration. It adds the debug location and enables WebSockets, which are required by the debugger.

    location /debug { 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; # to proxy WebSockets in nginx proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_pass [proxy server address]/debug; proxy_pass_header Sec-Websocket-Extensions; }

  7. Save and close your configuration file.

  8. Check for errors in your NGINX configuration by stopping and starting the server with the following commands:

    sudo nginx -s stop sudo nginx

    Alternatively, you can reload the configuration with the following command:

    sudo nginx -s reload

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 that support live updates. If you customize the common connection settings in the first location block, you should set the same custom parameters for the /api/eventSourceBus location. This guideline does not apply to the proxy_buffering setting, which, for the /api/eventSourceBus, should always be off. 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.

If you use a Java keystore, you need to convert it to the PKCS #12 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 PKCS #12 format:

  1. Use keytool to convert your current .jks file to the PKCS #12 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.

  2. 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] ...

  3. 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] ...

  4. 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] ...

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:

  1. Proxy rules should not block CORS-related HTTP headers:

    • Access-Control-Request-Method

    • Access-Control-Request-Headers

    • Access-Control-Allow-Origin

    • Access-Control-Allow-Credentials

    • Access-Control-Expose-Headers

    • Access-Control-Max-Age

    • Access-Control-Allow-Methods

    • Access-Control-Allow-Headers

  2. The proxy server should allow HTTP OPTIONS requests.

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

Condition

YouTrack displays the error message: "The live update connection is taking longer than expected."

Cause

Your reverse proxy server is buffering connections that support live updates.

Solution

Verify the current settings for your reverse proxy server and confirm that your connections are not subject to buffering.

  • For Apache installations, check the ProxyIOBufferSize directive.

  • For IIS:

    • Check that the Response buffer threshold is set to 0.

    • Check that the values for the Maximum URL length and Maximum query string parameters in the Request Filtering feature are configured as described in this setup guide.

    • Make sure that Dynamic Content Compression is disabled.

  • For NGINX, verify that the /api/eventSourceBus location is configured as described in this setup guide.

Condition

Your reverse proxy is configured as described in this guide or you are not using a reverse proxy. You continue to see the error message: "The live update connection is taking longer than expected."

Cause

You are using anti-virus or endpoint security software that blocks server-sent events.

Solution

Disable your software settings to allow automatic updates from the server.

Condition

Error 400: Oh-oh... Something went seriously wrong.

Cause

With an IIS reverse proxy, this can indicate that the value for the maxQueryStringLength property is too low. To confirm that this is the cause, disable custom errors mode in your web.config file (<customErrors mode="Off"/>) and check for a message like "The length of the query string for this request exceeds the configured maxQueryStringLength value."

Solution

Increase the value for the maxQueryStringLength property to at least 10000.

Condition

Error 413: Request Entity Too Large.

Cause

A user attempts to upload an attachment that exceeds the maximum body size accepted by the reverse proxy server.

Solution

Verify the current settings for your reverse proxy server and increase the maximum allowed size, if required. The recommended value for this setting is 10 megabytes.

  • For Apache installations, check the LimitRequestBody directive.

  • For IIS, check the uploadreadaheadsize config setting.

  • For NGINX, check the client_max_body_size directive.

Condition

Users are periodically logged out of YouTrack.

Cause

The built-in Hub service uses a hidden inline frame to refresh authentication tokens. If you have set the value for the X-Frame-Options header to DENY for your reverse proxy server, users are logged out when their tokens expire.

Solution

All responses that contain static content from the Hub service set the value for the X-Frame-Options header to SAMEORIGIN. To preserve this value, configure your reverse proxy server to use the X-Frame-Options: SAMEORIGIN directive for all static content from your YouTrack installation. If your YouTrack installation is connected to an external Hub service, set this directive for static content from Hub. For more information, see X-Frame-Options.

Condition

Issues and agile boards that are opened in new tabs are either blank, loading, or partially loaded.

Cause

Your proxy server doesn't support the number of connections that are required by pages that support live updates. The average upper limit is 30 connections per user. Users who open several issue views on different browser tabs can use up all the available connections.

For NGINX, you can confirm this condition by looking for worker_connections are not enough errors in the logs.

Solution

Tune the performance settings of your reverse proxy server to allow more connections to YouTrack.

  • For Apache installations, check the values for the MaxRequestWorkers and ThreadsPerChild directives. Increasing the values for these and other connection-related directives can improve performance.

  • For NGINX, check the values for the worker_rlimit_nofile and worker_connections directives. We recommend that you set the values for these directives to a minimum value of 4096 and 2048 respectively.

Last modified: 21 April 2023
TLS Server Certificates and Keystores Proxy Configuration