Child pages
  • Jaipur 2018.1 (build 57985) EAP2 Release Notes

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


The read-only server allows users read operations: view the build information, download artifacts, etc. during the downtime of the main server, e.g. during upgrade.

Starting Read-Only Node

A Read-Only node uses the same Data Directory and the same external database as the main TeamCity Server. Therefore, prerequisite of using the Read-Only node is to ensure that it has access to the data directory and database of the main TeamCity Server.

 In addition to the data directory shared with the main server, the Read-Only node requires a 'local' data directory where it stores some caches, unpacked external plugins and some other configuration. By default, the 'local' data directory is automatically created under the <Main Data Directory>/nodes/read_only_node path during the first start. You can override its location using property in the TeamCity start-up scripts.

To start a Read-Only node alongside the main TeamCity Server, do the following:

    1. Install the TeamCity software as usual: download a distribution package, unpack it or follow the installation wizard.
    2. Configure the TEAMCITY_DATA_PATH environment variable on the Read-Only node, make sure it points to the shared data directory.
    3. Add additional arguments to the TEAMCITY_SERVER_OPTS environment variable: TEAMCITY_SERVER_OPTS=-Dteamcity.server.role=read-only-server

High-Availability Installation

Using a read-only node it's possible to setup High-Availability TeamCity installation, that will have zero read downtime, i.e. when the main server is unavailable or is performing an upgrade requests may be routed to the read-only node. Such setup requires installing both the main server and the read-only node behind a reverse proxy, that should be configured to proxy requests to the main server while it's available and to the read-only in other cases.

For example, the following NGINX configuration will route requests to the read-only node only when the main server is not available or responds with 500 or 503 status codes, which generally means that it is starting or is performing an upgrade.  

Code Block
http {
    upstream backend {
        server teamcity-main.local:8111; # full internal address of the main server;
        server teamcity-ro.local:8111 backup; # full internal address of the read-only node;

    server {
        location / {
            proxy_pass          http://backend;
            proxy_next_upstream error timeout http_503 http_500;