Configuring Proxy Server

tip

TeamCity now allows configuring HTTPS access easily. These settings affect the built-in Tomcat server configuration and may break your existing proxy configuration.

For large public facing TeamCity installations, it is still recommended that you set up TeamCity behind a proxy.

Consider the example:
TeamCity server is installed at a local URL http://teamcity.local:8111/tc.
It is visible to the outside world as a public URL http://teamcity.public:400/tc.

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.

After configuring the proxy, you will also need to change the Server URL value in TeamCity Global Settings to the proxy URL.

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 Referer and 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.

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

## The following entries are required to allow the Agent Terminal feature to function with websockets
ProxyPass           /tc/plugins/teamcity-agent-terminal/ ws://teamcity.local:8111/tc/plugins/teamcity-agent-terminal/ connectiontimeout=240 timeout=1200
ProxyPassReverse    /tc/plugins/teamcity-agent-terminal/ ws://teamcity.local:8111/tc/plugins/teamcity-agent-terminal/

ProxyPass           /tc/app/agentTerminal/ ws://teamcity.local:8111/tc/app/agentTerminal/ connectiontimeout=240 timeout=1200
ProxyPassReverse    /tc/app/agentTerminal/ ws://teamcity.local:8111/tc/app/agentTerminal/

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

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
        }
    }
}

For a TeamCity Tomcat configuration, use the 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.

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

You need to change the "Connector" node in <TeamCity Home>/conf/server.xml file as below.

<Connector port="8111" protocol="org.apache.coyote.http11.Http11NioProtocol"
connectionTimeout="60000"
useBodyEncodingForURI="true"
socket.txBufSize="64000"
socket.rxBufSize="64000"
tcpNoDelay="1"
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.

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:

# For HTTP protocol
## The domain name or the IP address of the proxy host and the port:
teamcity.http.proxyHost=proxy.domain.com
teamcity.http.proxyPort=8080

## The hosts that should be accessed without going through the proxy, usually internal hosts. Provide a list of hosts, separated by the '|' character. The wildcard '*' can be used:
teamcity.http.nonProxyHosts=localhost|*.mydomain.com

## For an authenticated proxy add the following properties:
### Authentication type. "basic" and "ntlm" values are supported. The default is basic.
teamcity.http.proxyAuthenticationType=basic
### Login and Password for the proxy:
teamcity.http.proxyLogin=username
teamcity.http.proxyPassword=password

# For HTTPS protocol
## The domain name or the IP address of the proxy host and the port:
teamcity.https.proxyHost=proxy.domain.com
teamcity.https.proxyPort=8080

## The hosts that should be accessed without going through the proxy, usually internal hosts. Provide a list of hosts, separated by the '|' character. The wildcard '*' can be used:
teamcity.https.nonProxyHosts=localhost|*.mydomain.com

## For an authenticated proxy add the following properties:
### Authentication type. "basic" and "ntlm" values are supported. The default is basic.
teamcity.https.proxyAuthenticationType=basic
### Login and Password for the proxy:
teamcity.https.proxyLogin=login
teamcity.https.proxyPassword=password

warning

For external Git repositories, the aforementioned settings resolve connection issues only if you switch to the bundled JGit. If TeamCity uses the native Git, you need to manually setup proxy settings in your Git configuration. See the following articles for more information:

• Configure Git to use a proxy

• The git config reference

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 the TeamCity server using the following properties in the buildAgent.properties file:

## The domain name or the IP address of the proxy host and the port
teamcity.http.proxyHost=123.45.678.9
teamcity.http.proxyPort=8080

## If the proxy requires authentication, specify the login and password
teamcity.http.proxyLogin=login
teamcity.http.proxyPassword=password

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 squid.conf file.

The TeamCity server can be configured to use multiple nodes (or servers) for high availability and flexible load distribution. Refer to this article for the examples of NGINX and HAProxy configurations: Multinode Setup for High Availability.