Configuring Proxy Server
This article gives general recommendations on configuring a reverse proxy installed in front of the TeamCity Server web UI. It also contains example proxy configurations for outgoing connections and agent-server communication.
Set Up TeamCity Server Behind Proxy
To make sure TeamCity "knows" the actual absolute URLs used by the client to access the resources, you need to:
set up a reverse proxy as described below;
configure the Tomcat server bundled with TeamCity.
These URLs are used to generate absolute URLs in the client redirects and other responses.
Note: An internal TeamCity server should work under the same context (that is part of the URL after the host name) as it is visible from outside by an external address. See also the TeamCity server context changing instructions.
If you need to run the server under a different context, note that the context-changing proxy should conceal this fact from the TeamCity: for example, it should map server redirect URLs as well as cookies setting paths to the original (external) context.
The proxy should be configured with the generic web security in mind. Headers like
Origin and all unknown headers should be passed to the TeamCity web application in the unmodified form. For example, TeamCity relies on the
X-TC-CSRF-Token header added by the clients.
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.
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:
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.
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
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.
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
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).
TeamCity Tomcat Configuration
For a TeamCity Tomcat configuration, there are two options:
Use a dedicated "Connector" node in the server configuration with hard-coded public URL details and make sure the port configured in the connector is used only by the requests to the public URL configured.
Configure the proxy to pass due request headers:
X-Forwarded-Host(original request host),
X-Forwarded-Proto(original request protocol),
X-Forwarded-Port(original request port) and configure "RemoteIpValve" for the TeamCity Tomcat configuration.
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.
When the public server address is HTTPS, use the
scheme="https" attributes. If these attributes are missing, TeamCity will show a respective health report.
This approach can be used when the proxy server sets
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):
It is also recommended specifying the
internalProxies attribute with the regular expression matching only the IP address of the proxy server. For example,
Use Proxy for Outgoing Connections
This section describes configuring TeamCity to use a proxy server for outgoing HTTP connections. To connect TeamCity behind a proxy to Amazon EC2 cloud agents, see this section.
A TeamCity server can use a proxy server for certain outgoing HTTP connections to other services like issues trackers.
To point TeamCity to your proxy server, set the following internal properties:
Use Proxy to Connect Agents to TeamCity Server
This section covers the configuration of a proxy server for TeamCity agent-to-server connections.
On the TeamCity agent side, specify the proxy to connect to TeamCity server using the following properties in the
Note that the proxy has to be configured not to cache any TeamCity server responses; for example, if you use Squid, add "cache deny all" line to the