Configuring Proxy Server

Apache

Versions 2.4.5 or later are recommended. Earlier versions do not support the WebSocket protocol.

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:

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

NGINX

Versions 1.3 or later are recommended. Earlier versions do not support the WebSocket protocol.

IIS

To configure a TeamCity server behind an IIS reverse proxy:

1. Create a canonical name (CNAME) record for your TeamCity server.

2. Issue a certificate that will ensure a secure connection between the TeamCity server and external users. If the certificate was issued not by well-known certificate authority, you may need to manually add it to the Java Certificate Store on every machine that connects to TeamCity:

   keytool -importcert -file <cert file> -keystore <path to JRE installation>/lib/security/cacerts

3. Change the server URL to the proxy URL.

4. Edit the <TeamCity_Home_Directory>/conf/server.xml file to set up required TeamCity Tomcat server properties as described in the TeamCity Tomcat Configuration section.

5. Steps 5 to 8 are perfomed in Powershell. Use the Get-IISConfigSection and Set-IISConfigAttributeValue cmdlets to enable SSL flags:

   $ConfigSectionTC = Get-IISConfigSection -SectionPath "system.webServer/security/access" -Location "<IIS Website name>"; Set-IISConfigAttributeValue -AttributeName sslFlags -AttributeValue Ssl -ConfigElement $ConfigSectionTC;

6. Use the Set-WebConfigurationProperty cmdlet to add a server variable that allows the HTTP forwarded IP to be passed from the web requests:

   Set-WebConfigurationProperty -pspath "IIS:/" -Location "<IIS Website name>" -filter "system.webServer/rewrite/allowedServerVariables" -name "." -value @{name="HTTP_FORWARDED"} -FORCE

7. Enable proxy setting:

   Set-WebConfigurationProperty -pspath "MACHINE/WEBROOT/APPHOST" -filter "system.webServer/proxy" -name "." -value @{ enabled="true" } -FORCE

8. Disable the reverseRewriteHostInResponseHeaders parameter if you're using an external storage for TeamCity artifacts:

   Set-WebConfigurationProperty -pspath "MACHINE/WEBROOT/APPHOST" -filter "system.webServer/proxy" -name "." -value @{ reverseRewriteHostInResponseHeaders="false" } -FORCE

9. Modify the IIS web.config file as follows:

   <?xml version="1.0" encoding="UTF-8"?> <configuration> <system.web> <httpRuntime requestPathInvalidCharacters="" /> </system.web> <system.webServer> <rewrite> <rules useOriginalURLEncoding="true"> <rule name="teamcity" enabled="true" patternSyntax="Wildcard" stopProcessing="true"> <match url="*" /> <action type="Rewrite" url="http://localhost:80/{R:0}" /> <serverVariables> <set name="HTTP_FORWARDED" value="for={REMOTE_ADDR};by={LOCAL_ADDR};host=&quot;{HTTP_HOST}&quot;;proto=&quot;https&quot;" /> </serverVariables> </rule> </rules> </rewrite> <security> <requestFiltering allowDoubleEscaping="true"> <fileExtensions> <remove fileExtension=".config" /> </fileExtensions> <hiddenSegments> <remove segment="bin" /> </hiddenSegments> </requestFiltering> </security> </system.webServer> </configuration>

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.

• Settings that limit the maximum request name, response length, and response time are not too restrictive. See this article for more information: IIS-Related Issues.

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

IIS-related issues:

• If the "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target" error occurs, add your certificate to the same Java keystore TeamCity is using.

• If an incorrect server name is returned in HTTP 404 or 50x errors, check your redirect rules and the forwarded header.