Reverse Proxy Configuration

You can configure a YouTrack Server Docker installation to work behind a reverse proxy server.

To configure a reverse proxy for YouTrack Server:

Configure YouTrack to point to the base URL of the proxy server.
Configure the headers of your proxy server. This page links to configuration examples for Apache HTTP Server, HAProxy, IIS, NGINX, and Traefik in the YouTrack Support Knowledge Base.

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.

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 proxy server configuration examples linked from this page include 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 the YouTrack Docker Container

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:

Stop YouTrack: docker exec <containerId> stop
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.
Start YouTrack: docker start <containerId>

Configure Proxy Server Headers

For configuration examples, refer to the following articles in the YouTrack Support Knowledge Base:

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

Enabling WebSockets

Certain YouTrack features, such as the remote script debugger and Whiteboards, require additional configuration of the proxy server, including enabling WebSockets.

For WebSocket configuration examples, refer to the following articles in the YouTrack Support Knowledge Base:

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	Solution
Your reverse proxy server is buffering connections that support live updates.	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.

Cause

Solution

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

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	Solution
You are using antivirus or endpoint security software that blocks server-sent events.	Disable your software settings to allow automatic updates from the server.

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

Cause	Solution
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."	Increase the value for the `maxQueryStringLength` property to at least `10000`.

Condition — Error 413: Request Entity Too Large.

Cause	Solution
A user attempts to upload an attachment that exceeds the maximum body size accepted by the reverse proxy server.	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.

Cause

Solution

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

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

Cause

Solution

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.

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

Cause

Solution

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.

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.

19 August 2026