Configuring Proxy Server

Apache

Versions 2.4.5 or later are recommended. Earlier versions do not support the WebSocket protocol, so you should use the settings described in the previous documentation version.

When using Apache, make sure to use the Dedicated "Connector" node approach for configuring TeamCity server.

LoadModule  proxy_module          /usr/lib/apache2/modules/mod_proxy.so
LoadModule  proxy_http_module     /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule  headers_module        /usr/lib/apache2/modules/mod_headers.so
LoadModule  proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so

ProxyRequests       Off
ProxyPreserveHost   On
ProxyPass           /tc/app/subscriptions ws://teamcity.local:8111/tc/app/subscriptions connectiontimeout=240 timeout=1200
ProxyPassReverse    /tc/app/subscriptions ws://teamcity.local:8111/tc/app/subscriptions

ProxyPass           /tc http://teamcity.local:8111/tc connectiontimeout=240 timeout=1200
ProxyPassReverse    /tc http://teamcity.local:8111/tc

Note the order of the ProxyPass rules: conflicting ProxyPass rules must be sorted starting with the longest URLs first.

By default, Apache allows only a limited number of parallel connections that may be insufficient when using the WebSocket protocol. For instance, it may result in the TeamCity server not responding when a lot of clients open the web UI. To fix it, you may need to fine-tune the Apache configuration.

For example, on Unix, you should switch to mpm_worker and configure the maximum number of simultaneous connections:

<IfModule mpm_worker_module>
    ServerLimit 100
    StartServers 3
    MinSpareThreads 25
    MaxSpareThreads 75
    ThreadLimit 64
    ThreadsPerChild 25
    MaxClients 2500
    MaxRequestsPerChild 0
</IfModule>

On Windows, you may need to increase the ThreadsPerChild value as described in the Apache documentation.

NGINX

For the NGINX configuration below, use the "RemoteIpValve" Approach for configuring the TeamCity server.

Versions 1.3 or later are recommended. Earlier versions do not support the WebSocket protocol, so you should use the settings described in the previous documentation version.

http {
    # ... default settings here
    proxy_read_timeout     1200;
    proxy_connect_timeout  240;
    client_max_body_size   0;    # maximum size of an HTTP request. 0 allows uploading large artifacts to TeamCity

    map $http_upgrade $connection_upgrade { # WebSocket support
        default upgrade;
        '' '';
    }

    server {
        listen       400; # public server port
        server_name  teamcity.public; # public server host name

        location / { # public context (should be the same as internal context)
            proxy_pass http://teamcity.local:8111; # full internal address
            proxy_http_version  1.1;
            proxy_set_header    Host $server_name:$server_port;
            proxy_set_header    X-Forwarded-Host $http_host;    # necessary for proper absolute redirects and TeamCity CSRF check
            proxy_set_header    X-Forwarded-Proto $scheme;
            proxy_set_header    X-Forwarded-For $remote_addr;
            proxy_set_header    Upgrade $http_upgrade; # WebSocket support
            proxy_set_header    Connection $connection_upgrade; # WebSocket support
        }
    }
}

Other Servers

Make sure to use a performant proxy with due (high) limits on request (upload) and response (download) size and timeouts (at least tens of minutes and gigabyte, according to the sizes of the codebase and artifacts).

It is recommended to use a proxy capable of working with the WebSocket protocol as this helps the UI to refresh quicker.

Generally, you need to configure the TeamCity server so that it "knows" about the original URL used by the client and can generate correct absolute URLs accessible for the client. The preferred way to achieve that is to pass the original Host header to TeamCity. An alternative method is to set X-Forwarded-Host header to the original Host header's value.

Note that whenever the value of the Host header is changed by the proxy (while it is recommended to preserve the original Host header value) and no X-Forwarded-Host header with the original Host value is provided, the values of the Origin and Referer headers should be mapped correspondingly if they contain the original Host header value (if they do not, they should not be set in order not to circumvent TeamCity CSRF protection).

Select a proper approach from the section below and configure the proxy accordingly.

Common Misconfigurations

Check that your reverse proxy (or a similar tool) conforms to the following requirements:

• URLs with paths starting with a dot (.) are supported (path to hidden artifacts start contain the .teamcity directory).

• URLs with a colon (:) are supported (many TeamCity resources use the colon). Related IIS setting. Symptom: build has no artifacts with the "No user-defined artifacts in this build" text even if there are artifacts.

• Maximum response length / time are not too restrictive (since TeamCity can serve large files to slow clients, the responses can be of Gb in size and hours in time).

• gzip Content-Encoding is fully supported. For example, certain IIS configurations can result in the "Loading data..." in the UI and 500 HTTP responses (see the related issue).

Dedicated "Connector" Node Approach

This approach can be used with any proxy configuration, provided the configured port is receiving requests only to the configured public URL.

Set up the proxying server to redirect all requests to teamcity.public:400 to a dedicated port on the TeamCity server (8111 in the example below) and change the "Connector" node in <TeamCity Home>/conf/server.xml file as below. Note that the "Connector" port configured this way should only be accessible via the configured proxy's address. If you also want to make TeamCity port accessible directly, use a separate "Connector" node with a dedicated port value for that.

<Connector port="8111" protocol="org.apache.coyote.http11.Http11NioProtocol"
               connectionTimeout="60000"
               useBodyEncodingForURI="true"
               socket.txBufSize="64000"
               socket.rxBufSize="64000"
               tcpNoDelay="1"
               proxyName="teamcity.public"
               proxyPort="400"
               secure="false"
               scheme="http"
               />

When the public server address is HTTPS, use the secure="true" and scheme="https" attributes. If these attributes are missing, TeamCity will show a respective health report.

"RemoteIpValve" Approach

This approach can be used when the proxy server sets X-Forwarded-Proto, X-Forwarded-Port request headers to the values of the original URL. Also, while not critical for the most setups, this approach can be used to make sure the original client IP is passed to the TeamCity server correctly. This is important for legacy agents' bidirectional communication.

Add the following into the Tomcat main <Host> node of the conf\server.xml file (see also Tomcat doc):

<Valve
   className="org.apache.catalina.valves.RemoteIpValve"
   remoteIpHeader="x-forwarded-for"
   protocolHeader="x-forwarded-proto"
   portHeader="x-forwarded-port"
   />

It is also recommended specifying the internalProxies attribute with the regular expression matching only the IP address of the proxy server. For example, internalProxies="192\.168\.0\.1".