How To...

Choose OS/Platform for TeamCity Server

Once the server/OS fulfills the requirements, TeamCity can run on any system. Please also review the requirements for the integrations you plan to use, for example the following functionality requires or works better when TeamCity server is installed under Windows:

• VCS integration with TFS

• VCS integration with VSS

• Windows domain logins (can also work under Linux, but may be less stable), especially NTLM HTTP authentication

• NuGet feed on the server (can also work under Linux, but may be less stable)

• Agent push to Windows machines

If you have no preference, Linux platforms may be more preferable due to more effective file system operations and the level of required general OS maintenance.

Final Operating System choice should probably depend more on the available resources and established practices in your organization.

If you choose to install 64 bit OS, TeamCity can run under 64 bit JDK (both server and agent). However, unless you need to provide more than 1Gb memory for TeamCity, the recommended approach is to use 32 bit JVM even under 64 bit OS. Our experience suggests that using 64 bit JVM does not increase performance a great deal. At the same time it does increase memory requirements to almost the scale of 2. See a note on memory configuration.

Estimate Hardware Requirements for TeamCity

The hardware requirements differ for the server and the agents.

The agent hardware requirements are basically determined by the builds that are run. Running TeamCity agent software introduces a requirement for additional CPU time (but it can usually be neglected comparing to the build process CPU requirements) and additional memory: about 500Mb. The disk space required corresponds to the disk usage by the builds running on the agent (sources checkouts, downloaded artifacts, the disk space consumed during the build; all that combined for the regularly occurring builds). Although you can run a build agent on the same machine as the TeamCity server, the recommended approach is to use a separate machine (it may be virtual) for each build agent. If you chose to install several agents on the same machine, please consider the possible CPU, disk, memory or network bottlenecks that might occur. The Performance Monitor build feature can help you in analyzing live data.

The server hardware requirements depend on the server load, which in its turn depends significantly on the type of the builds and server usage. Consider the following general guidelines.

Database Note : When using the server extensively, the database performance starts to play a greater role. For reliability and performance reasons you should use external database. Please see the notes on choosing external database. The database size requirements naturally vary based on the amount of data stored (number of builds, number of tests, etc.) The active server database usage can be estimated at several gigabytes of data per year.

Overview of the TeamCity hardware resources usage :

• CPU: TeamCity utilizes multiple cores of the CPU, so increasing number of cores makes sense. For non-trivial TeamCity usage at least 4 CPU cores are recommended.

• Memory: used by the TeamCity server main process and child processes (used for Maven integration, version control integration, Kotlin DSL execution). See the notes on the main process memory usage. Generally, you will probably not need to dedicate more than 4G of memory to TeamCity server if you do not plan to run more then 100 concurrent builds (agents), support more then 200 online users or work with large repositories.

• HDD/disk usage: This sums up mainly from the temp directory usage (<TeamCity Home>/temp and OS temp directory) and .BuildServer/system usage. Performance of the TeamCity server highly depends on the disk system performance. As TeamCity stores large amounts of data under .BuildServer/system (most notably, VCS caches and build results) it is important that the access to the disk is fast (in particular reading/writing files in multiple threads, listing files with attributes). Ensuring disk has good performance is especially important if you plan to store the data directory on a network drive.

• Network: This mainly sums up from the traffic from VCS servers, to clients (web browsers, IDE, etc.) and to/from build agents (send sources, receive build results, logs and artifacts).

The load on the server depends on :

• number of build configurations;

• number of builds in the history;

• number of the builds running daily;

• amount of data consumed and produced by the builds (size of the used sources and artifacts, size of the build log, number and output size of unit tests, number of inspections and duplicates hits, size and number of produced artifacts, etc.);

• cleanup rules configured

• number of agents and their utilization percentage;

• number of users having TeamCity web pages open;

• number of users logged in from IDE plugin;

• number and type of VCS roots as well as the configured checking for changes interval for the VCS roots. VCS checkout mode is relevant too: server checkout mode generates greater server load. Specific types of VCS also affect server load, but they can be roughly estimated based on native VCS client performance;

• number of changes detected by TeamCity per day in all the VCS roots;

• the size of the repositories TeamCity works with;

• total size of the sources checked out by TeamCity daily.

A general example of hardware configuration capable to handle up to 100 concurrently running builds and running only TeamCity server can be: Server-suitable modern multi-core CPU, 8Gb of memory, fast network connection, fast and reliable HDD, fast external database access

Based on our experience, a modest hardware like Intel 3.2 GHz dual core CPU, 3.2Gb memory under Windows, 1Gb network adapter, single HDD can provide acceptable performance for the following setup:

• 60 projects and 300 build configurations (with one forth being active and running regularly);

• more than 300 builds a day;

• about 2Mb log per build;

• 50 build agents;

• 50 web users and 30 IDE users;

• 100 VCS roots (mainly Perforce and Subversion using server checkout), average checking for changes interval is 120 seconds;

• more than 150 changes per day;

• Kotlin DSL is not used;

• the database (MySQL) is running on the same machine;

• TeamCity server process has -Xmx1100mJVM setting.

The following configuration can provide acceptable performance for a more loaded TeamCity server: Intel Xeon E5520 2.2 GHz CPU (4 cores, 8 threads), 12Gb memory under Windows Server 2008 R2 x64, 1Gb network adapter, 3 HDD RAID1 disks (general, one for artifacts, logs and caches storage, and one for the database storage) Server load characteristics:

• 150 projects and 1500 build configurations (with one third being active and running regularly);

• more than 1500 builds a day;

• about 4Mb log per build;

• 100 build agents;

• 150 web users and 40 IDE users;

• 250 VCS roots (mainly Git, Hg, Perforce and Subversion using agent-side checkout), average checking for changes interval is 180 seconds;

• more than 1000 changes per day;

• the database (MySQL) is running on the same machine;

• TeamCity server process has -Xmx3700mx64 JVM setting.

However, to ensure peak load can be handled well, more powerful hardware is recommended.

HDD free space requirements are mainly determined by the number of builds stored on the server and the artifacts size/build log size in each. Server disk storage is also used to store VCS-related caches and you can estimate that at double the checkout size of all the VCS roots configured on the server.

If the builds generate large number of data (artifacts/build log/test data), using fast hard disk for storing .BuildServer/system directory and fast network between agents and server are recommended.

The general recommendation for deploying large-scale TeamCity installation is to start with a reasonable hardware while considering hardware upgrade. Then increase the load on the server (e.g. add more projects) gradually, monitoring the performance characteristics and deciding on necessary hardware or software improvements. There is also a benchmark plugin which can be used to estimate the number of simultaneous build the current server installation can handle. Anyway, best administration practices are recommended like keeping adequate disk defragmentation level, etc.

Starting with an adequately loaded system, if you then increase the number of concurrently running builds (agents) by some factor, be prepared to increase CPU, database and HDD access speeds, amount of memory by the same factor to achieve the same performance. If you increase the number of builds per day, be prepared to increase the disk size.

If you consider cloud deployment for TeamCity agents (e.g. on Amazon EC2), please also review Setting Up TeamCity for Amazon EC2

A note on agents setup in JetBrains internal TeamCity installation: We use both separate machines each running a single agent and dedicated "servers" running several virtual machines each of them having a single agent installed. Experimenting with the hardware and software we settled on a configuration when each core7i physical machine runs 3 virtual agents, each using a separate hard disk. This stems form the fact that our (mostly Java) builds depend on HDD performance in the first place. But YMMV.

TeamCity is known to work well with 500+ build agents (500 concurrently running builds actively logging build run-time data). In synthetic tests the server was functioning OK with as many as 1000 concurrent builds (the server with 8 cores, 32Gb of total memory running under Linux, and MySQL server running on a separate comparable machine). The load on the server produced by each build depends on the amount of data the build produces (build log, tests number and failure details, inspections/duplicates issues number, etc.). Keeping the amount of data reasonably constrained (publishing large outputs as build artifacts, not printing those into standard output; tweaking inspection profiles to report limited set of the most important inspection hits, etc.) will help scale the server to handle more concurrent builds. If you need much more agents/parallel builds, it is recommended to use several nodes setup. If a substantially large amount of agents is required, it is recommended to consider using several separate TeamCity instances and distributing the projects between them. We constantly work on TeamCity performance improvements and are willing to work closely with organizations running large TeamCity installations to study any performance issues and improve TeamCity to handle larger loads. See also a related post on the maximum number of agents which TeamCity can handle

See also a related post: description of a substantial TeamCity setup.

Network Traffic between the Server and the Agents

The traffic mostly depends on the settings as some of them include transferring binaries between the agent and the server. The most important flows of traffic between the agent and the server are:

• agent retrieves commands from the server: these are typically build start tasks which basically include a dump of the build configuration settings and the full set of build parameters. The latter can be large (e.g. megabytes) in case of a large build chain. The parameters can be reviewed on the build's Parameters tab;

• agent periodically sends current status data to the server (this includes all the agents parameters which can be reviewed on the agent's Agent Parameters tab);

• during the build, the agent sends build log messages and parameters data back to the server. These can be reviewed on the Build Log and Parameters tabs of the build;

• (when the server-side checkout mode is used) the agent downloads the sources before the build (as a full or incremental patch) from the server;

• (when an artifact dependency is configured) the agent downloads build artifacts of other builds from the server before starting a build;

• (when artifacts are configured for a build) the agent uploads build artifacts to the server;

• some runners (like coverage or code analysis) include automatic uploading of their results' reports to the server.

Configuring TeamCity Server for Performance

Here are some recommendations to tweak TeamCity server setup for better performance. The list for production server use is a prerequisite:

• Regularly review reported Server Health reports (including hidden ones)

• Use a separate reverse proxy server (e.g. NGINX) to handle HTTPS

• Use a separate server for the external database and monitor the database performance

• Monitor the server's CPU and IO performance, increase hardware resources as necessary (see also hardware notes)

• Make sure clean-up is configured for all the projects with a due retention policy, make sure clean-up completely finishes regularly (check Administration / Clean-Up page)

• Consider ensuring good IO performance for the <TeamCity Data Directory>/system/caches directory, e.g. by moving it to a separate local drive (or storing on a local drive you choose to store the TeamCity Data Directory on a network storage)

• Regularly archive obsolete projects

• Regularly review the installed not bundled plugins and remove those not essential for the server functioning

• Consider using agent-side checkout whenever possible

• Make sure the build logs are not huge (tens megabytes at most, better less than 10 Mb)

• If lots VCS roots are configured on the server, consider configuring repository commit hooks instead of using polling for changes or at least increase VCS polling interval to 300 seconds or more

• If the server is often used by large number of users (e.g. more than 1000), consider reducing the frequency of background UI requests their by increasing UI refresh intervals

• When regularly exceeding 500 concurrently running builds which log a lot of data, consider using Several Nodes Setup

Retrieve Administrator Password

On the first start with the empty database, TeamCity displays the Administrator Setup page which allows creating a user with full administrative permissions (assigning the System Administrator role).

If you want to regain access to the system and you cannot log in as a user with the System Administrator role, you can log in as a super user and change the existing administrator account password or create a new account with the System Administrator role.

It is also possible to use REST API to add the System Administrator role to any existing user.

If you use built-in authentication and have correct email specified, you can reset the password from the login page.

Estimate External Database Capacity

It is quite hard to provide the exact numbers when setting up or migrating to an external database, as the required capacity varies greatly depending on how TeamCity is used.

The database size and database performance are crucial aspects to consider.

Database Size

The size of the database will depend on:

• how many builds are started every day

• how many test are reported from builds

• clean-up rules (retention policy)

• cleanup schedule

We recommend the initial size of data spaces to be 4 GB. When migrating from the internal database, we suggest at least doubling the size of the current internal database. For example, the size of the external database (without the Redo Log files) of the internal TeamCity server in JetBrains is about 50 GB. Setting your database to grow automatically helps to increase file sizes to a pre-determined limit when necessary, which minimizes the effort to monitor disk space.

Allocating 1 GB for the redo log (see the table below) and undo files is sufficient in most cases.

Database Performance

The following factors are to be taken into account:

• type of database (RDBMS)

• number of agents (which actually means the number of builds running in parallel)

• number of web pages opened by all users

• clean-up rules (retention policy)

It is advised to place the TeamCity Data directory and database data files on physically different hard disks (even when both the TeamCity server and RDBMS share the same host).

Placing redo logs on a separate physical disk is also recommended especially in case of the high number of agents (50 and more).

The redo log (or a similar entity) naming for different RDBMS:

PostgreSQL: We recommend using version 9.2+, which has a lot of query optimization features. Also see the information on the write-ahead-log (WAL) in the PostgreSQL documentation

Oracle: it is recommended to keep statistics on: all automatically gathered statistics should be enabled (since Oracle 10.0, this is the default set-up). Also see the information on redo log files in the Oracle documentation.

MS SQL Server: it is NOT recommended to use the jTDS driver: it does not work with nchar/nvarchar, and to preserve unicode streams it may cause queries to take a long time and consume a lot of IO. Also see the information on redo log in the Microsoft Knowledge base. If you use jTDS, please migrate.

MySQL: the query optimizer might be inefficient: some queries may get a wrong execution plan causing them to take a long time and consume huge IO.

Estimate the Number of Required Build Agents

There are no precise data and the number of required build agents depends a lot on the server usage pattern, type of builds, team size, commitment of the team to CI process, etc. The best way is to start with the default 3 agents and see how that plays with the projects configured, then estimate further based on that.

You might want to increase the number of agents when you see:

• builds waiting for an idle agent in the build queue;

• more changes included into each build than you find comfortable (e.g. for build failures analysis);

• necessity for different environments.

We've seen patterns of having an agent per each 20 build configurations (types of builds). Or a build agent per 1-2 developers.

See also notes on maximum supported number of agents.

Setup TeamCity in Replication/Clustering Environment

TeamCity only supports a single instance of the main server, but it is possible to add secondary node (to provide view-only UI over the current data) and running builds node to collect the running builds data form the agents. All three nodes need to be connected to the same TeamCity Data Directory and the database.

To address fast disaster recovery scenarios, TeamCity supports active - failover (cold standby) approach: the data that the TeamCity server uses can be replicated and a solution put in place to start a new server using the same data if the currently active server malfunctions.

As to the data, the TeamCity server uses both database and file storage (Data Directory). You can browse through TeamCity Data Backup and TeamCity Data Directory pages in to get more information on TeamCity data storing. Basically, both TeamCity data directory on the disk and the database which TeamCity uses must remain in a consistent state and thus must be replicated together. Only a single TeamCity server instance should use the database and data directory at any time.

Ensure that the distribution of the TeamCity failover/backup server is of exactly the same version as the main server. It is also important to ensure the same server environment/startup options like memory settings, etc.

TeamCity agents farm can be reused between the main and the failover servers. Agents will automatically connect to the new server if you make the failover server to be resolved via the old server DNS name and agents connect to the server using the DNS name. See also information on switching from one server to another. If appropriate, the agents can be replicated just as the server. However, there is no need to replicate any TeamCity-specific data on the agents except for the conf\buildAgent.properties file as all the rest of the data can typically be renewed from the server. In case of replicated agents farm, the replica agents just need to be connected to the failover server.

In case of two servers installations for redundancy purposes, they can use the same set of licenses as only one of them is running at any given moment.

TeamCity Security Notes

The following notes are provided for your reference only and are not meant to be complete or accurate in their entirety.

TeamCity is developed with security concerns in mind, and reasonable efforts are made to make the system invulnerable to different types of attacks. We work with third-parties on assessing TeamCity security using security scanners and penetration tests. We aim to promptly address newly discovered security issues in the nearest bug-fix releases for the most recent TeamCity major version. However, the general assumption and recommended setup is to deploy TeamCity in a trusted environment with no possibility for it to be accessed by malicious users.

Along with these guidelines, please review notes on configuring the TeamCity server for production use. For the list of disclosed security-related issues, see our public issue tracker and the "Security" section in the release notes. It is recommended to upgrade to newly released TeamCity versions as soon as they become available as they can contain security-related fixes.

Note that since TeamCity 2017.2 the TeamCity Windows installer modifies permisisons of the TeamCity installation directory not to use inheritable permissions and explicitly grants access to the directory to the Administrators user group and the accrount under which the service is configured to run. It is strongly recommended to restrict permissions to the TeamCity Data Directory in the same way.

Additional security-related settings

Consider adding the " teamcity.installation.completed=true " line into the < >\conf\teamcity-startup.propertiesfile - this will prevent the server started with the empty database from granting access to the machine for the first coming user.

TeamCity has no built-in protection against DoS (Denial-of-service) attack: high rate of requests can overload the server and make it not responsive. If your TeamCity instance is deployed in the environment which allows such service abuse, implement the protection on the reverse proxy level.

Short checklist (see below for full notes)

• You are running the latest released TeamCity version and are ready to upgrade to the newly released versions within weeks

• Access to the TeamCity web interface is secured using HTTPS (e.g. with the help a proxying server like NGINX). Best practices for securing web applications are employed for the TeamCity web interface. e.g.: It is not possible to access the server using HTTP protocol. Reverse proxy does not strip Referer request header

• The TeamCity server machine does not run agents (at least under the user permitted to read the TeamCity server's home directory and TeamCity Data Directory)

• TeamCity server and agents processes are run under limited users with minimal required permissions. Installation directories are readable and writable only by a limited set of OS users. The conf\buildAgent.properties file and server logs as well as the Data Directory are only readable by OS users who represent administrators of the services, because reading those locations may allow taking over the agent or server respectively.

• Guest user and user registration is disabled or roles are reviewed for guest and theAll Users group

• TeamCity users with administrative permissions have non-trivial passwords

• If you have external authentication configured (such as LDAP), the built-in authentication module is disabled

• Passwords are not printed into the build log, not stored in build artifacts, nor are they stored in non-password parameters

Security-related Risks Evaluation

Here are some notes on different security-related aspects:

• man-in-the middle concerns

  • between the TeamCity server and the user's web browser: It is advised to use HTTPS for the TeamCity server. During login, TeamCity transmits the user login password in an encrypted form with a moderate encryption level.

  • between a TeamCity agent and the TeamCity server: see the section.

  • between the TeamCity server and other external servers (version control, issue tracker, etc.): the general rules apply as for a client (the TeamCity server in the case) connecting to the external server, see the guidelines for the server in question.

• users that have access to the TeamCity web UI: the specific information accessible to the user is defined via TeamCity user roles.

• users who can change the code that is used in the builds run by TeamCity (including committers in any branches/pull requests if they are built on TeamCity):

  • can do everything what can do the system user under whom the TeamCity agent is running, have access to OS resources and other applications installed on the agent machines where their builds can run.

  • can access and change source code of other projects built on the same agent, modify the TeamCity agent code, publish any files as artifacts for the builds run on the agent (which means the files can be then displayed in the TeamCity web UI and expose web vulnerabilities or can be used in other builds), etc.

  • can impersonate a TeamCity agent (run a new agent looking the same to the TeamCity server).

  • can do everything that users with the "View build configuration settings" permission for all the projects on the server can do (see below).

  • can retrieve settings of the build configurations where the builds are run, including the values of the password fields.

  • can download artifacts from any build on the server. Hence, it is advised to run TeamCity agents under an OS account with only necessary set of permissions and use the agent pools feature to ensure that projects requiring a different set of access are not built on the same agents.

• users with the "View build configuration settings" permission (the "Project developer" TeamCity role by default) can view all the projects on the server, but since TeamCity 9.0 there is a way to restrict this, see details in the corresponding issue TW-24904.

• users with the "Edit project" permission (the "Project Administrator" TeamCity role by default) in one project, by changing settings can retrieve artifacts and trigger builds from any build configuration they have only the view permission for (TW-39209). The users might also be able to make the TeamCity server run any executable located on the server.

• users with the "Change server settings" permission (the "System Administrator" TeamCity role by default): It is assumed that the users also have access to the computer on which the TeamCity server is running under the user account used to run the server process. Thus, the users can get full access to the machine under that OS user account: browse file system, change files, run arbitrary commands, etc.

• TeamCity server computer administrators: have full access to TeamCity stored data and can affect TeamCity executed processes. Passwords that are necessary to authenticate in external systems (like VCS, issue trackers, etc.) are stored in a scrambled form in TeamCity Data Directory and can also be stored in the database. However, the values are only scrambled, which means they can be retrieved by the users who have access to the server file system or database.

• Users who have read access for TeamCity server logs (TeamCity server home directory) can escalate their access to TeamCity server administrator

• Users who have read access to TeamCity Data Directory can access all the settings on the server, including configured passwords

• Users who have read access to the build artifacts in TeamCity Data Directory (<TeamCity Data Directory>\system\artifacts) get the same permissions as users with the "View build runtime parameters and data" permission (in particular, with access to the values of all the password parameters used in the build)

• TeamCity agent computer administrators: same as "users who can change code that is used in the builds run by TeamCity".

• It is recommended to distribute projects among agents, so that one TeamCity agent would not run builds of several projects whose developers and administrators should not get access to each other's projects. The recommended way to distribute projects is to use the agent pools feature and make sure that the "Default" agent pool has no agents as a project can be assigned to the Default pool after a certain reconfiguration (i.e. when there is no other pool the project is assigned to).

• When storing settings in VCS is enabled:

  • any user who can access the settings repository (including users with "View file content" permission for the build configurations using the same VCS root) can see the settings and retrieve the actual passwords based on their stored scrambled form

  • any user who can modify settings in VCS for a single build configuration built on the server, via changing settings can retrieve artifacts and trigger builds from any build configuration they have only view permission for (TW-39192).

  • users who can customize build configuration settings on a per-build basis (e.g. one who can run personal builds when versioned settings are set to "use settings from VCS") via changing settings in a build can retrieve artifacts and trigger builds from any build configuration they have only view permission for (TW-46065).

• Other:

  • TeamCity web application vulnerabilities: the TeamCity development team makes a reasonable effort to fix any significant vulnerabilities (like cross-site scripting possibilities) once they are uncovered. Please note that any user that can affect build files ("users who can change code that is used in the builds run by TeamCity" or "TeamCity agent computer administrators") can make a malicious file available as a build artifact that will then exploit cross-site scripting vulnerability. (TW-27206)

  • TeamCity agent is fully controlled by the TeamCity server: since TeamCity agents support automatic updates download from the server, agents should only connect to a trusted server. An administrator of the server computer can force execution of arbitrary code on a connected agent.

  • Binaries of the agent plugins installed on the server are available to anyone who can access the server URL

What Encryption is Used by TeamCity

TeamCity tries not to pass password values in the web UI (from a browser to the server) in clear text and uses RSA with 1024-bit key to encrypt them. However, it is recommended to use the TeamCity web UI only via HTTPS so this precaution should not be relevant. TeamCity stores passwords in the settings (where the original password value is necessary to perform authentication in other systems) in a scrambled form. The scrambling is done using 3DES with a fixed key.

Configure Newly Installed MySQL Server

If MySQL server is going to be used with TeamCity in addition to the basic setup, you should review and probably change some of the MySQL server settings. If MySQL is installed on Windows, the settings are located in my.ini file which usually can be found under MySQL installation directory. For Unix-like systems the file is called my.cnf and can be placed somewhere under /etc directory. Read more about configuration file location in MySQL documentation. Note: you'll need to restart MySQL server after changing settings in my.ini|my.cnf.

The following settings should be reviewed and/or changed:

InnoDB database engine

Make sure you're using InnoDB database engine for tables in TeamCity database. You can check what engine is used with help of this command:

or for all tables at once:

max_connections

You should ensure max_connections parameter has bigger value than the one specified in TeamCity <TeamCity data directory>/config/database.properties file.

innodb_buffer_pool_size and innodb_log_file_size

Specifying a too small value in innodb_buffer_pool_size may significantly affect performance:

We recommend to start with 2Gb and increase it if you experience slowness and have enough memory. After increasing buffer pool size you should also change size of the http://dev.mysql.com/doc/refman/5.6/en/innodb-parameters.html#sysvar_innodb_log_file_size setting (its value can be calculated as innodb_buffer_pool_size/N, where N is the number of log files in the group (2 by default)):

innodb_file_per_table

For better performance you can enable the so-called per-table tablespaces. Note that once you add innodb_file_per_table option new tables will be created and placed in separate files, but tables created before enabling this option will still be in the shared tablespace. You'll need to re-import database for them to be placed in separate files.

innodb_flush_log_at_trx_commit

If TeamCity is the only application using MySQL database then you can improve performance by setting innodb_flush_log_at_trx_commit variable to 2 or 0:

Note: it is not important for TeamCity that database offers full ACID behavior, so you can safely change this variable.

log files on different disk

Placing the MySQL log files on different disk sometimes helps improving performance. You can read about it in MySQL documentation.

Setting The Binary Log Format

If the default MySQL binary logging format is not MIXED (it depends on the version of MySQL you are using), then it should be explicitly set to MIXED:

Enable additional diagnostics

To get additional diagnostics data in case of some database-specific errors, grant more permissions for a TeamCity database user via SQL command:

Configure Newly Installed PostgreSQL Server

For better TeamCity server performance, it is recommended to change some of the parameters of the newly installed PostgreSQL server. You can read more about PostgreSQL performance optimization in PostgreSQL Wiki.

The parameters below can be changed in the postgresql.conf file located in the in PostgreSQL's data directory.

shared_buffers

The default value of http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-SHARED-BUFFERS parameter is too small and should be increased:

checkpoint_segmentscheckpoint-related parameters

For write-intensive applications such as TeamCity, it is recommended to change some of the checkpoint-related parameters:

For PostgreSQL 9.5 and later:

For versions prior to PostgreSQL 9.5:

synchronous_commit

If TeamCity is the only application using the PostgreSQL database, we recommend disabling the http://www.postgresql.org/docs/current/static/runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT parameter:

Set Up TeamCity behind a Proxy Server

This section covers the recommended setup of reverse-proxy servers installed in front of the TeamCity server web UI. Configuring HTTPS on the proxy level is recommended, but is out of the scope of these instructions - refer to the documentation of the proxy server for that.

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

You need to set up a reverse proxy (see Proxy-Server-Setup below) and also configure TeamCity's bundled Tomcat server (see TeamCity-Tomcat-Configuration below) to make sure TeamCity "knows" the actual absolute URL used by the client to access the resources. These URLs are then used to generate absolute URLs in client redirects and other responses.

Note: An internal TeamCity server should work under the same context (i.e. part of the URL after the host name) as it is visible from outside by an external address. See also TeamCity server context changing instructions. If you still need to run the server under a different context, note that context changing proxy should conceal this fact from the TeamCity: e.g. it should map server redirect URLs as well as cookies setting paths to the original (external) context.

Proxy Server Setup

The proxy should be configured with generic web security in mind. e.g. headers like Referer and Origin should usually be passed to the TeamCity web application in the unmodified form. Also, unknown HTTP request headers should be passed to the TeamCity web application unmodified. For example TeamCity relies on " X-TC-CSRF-Token" header added by the clients.

Apache

Versions 2.4.5+ are recommended. Earlier versions do not support the WebSocket protocol, so use the settings noted in the previous documentation version.

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

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

Note that 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

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

Versions 1.3+ are recommended. Earlier versions do not support the WebSocket protocol, so use the settings noted in the previous documentation version.

Common misconfigurations

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

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

• URLs with a colon (":" symbol) are supported (many TeamCity resources use the colon). Related IIS setting. Symptom: build has no artifacts with "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. e.g. certain IIS configurations can result in the "Loading data..." in UI and 500 HTTP responses (see the related issue)

OtherServersOther 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 that helps UI to refresh sooner.

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

Note that whenever the value of the "Host" header is changed by the proxy (while it is recommended to preserve 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.

TeamCity Tomcat Configuration

For a due 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 that the port configured in the connector is used only by the requests to the public URL configured.

• configure proxy to pass due request headers: "Host" or "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.

Proxy-Tomcat-ConnectorDedicated "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 "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 secure="true" and scheme="https" attributes.

Proxy-Tomcat-RemoteIpValve"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):

It is also recommended to specify internalProxies attribute with the regular expression matching only IP address of the proxy server. e.g. internalProxies = "192\.168\.0\.1"

Configure HTTPS for TeamCity Web UI

TeamCity does not provide out-of-the-box support for HTTPS access (see TW-12976). It is highly recommended to set up a reverse proxy like Nginx or Apache in front of TeamCity that would handle HTTPS and use HTTP TeamCity server port as the upstream. HTTPS-related configuration of the proxy is not specific for TeamCity and is generic as for any Web application. Make sure to configure the reverse proxy per our recommendations below. Generic web application best practices apply (like disabling http access to TeamCity at all).

For small servers, you can set up HTTPS via the internal Tomcat means, but this is not recommended as it may significantly increase the CPU load.

For configuring clients to access TeamCity server via HTTPS while using self-signed certificate, check the related instructions.

Configure TeamCity to Use Proxy Server for Outgoing Connections

This section describes configuring TeamCity to use proxy server for certain outgoing HTTP connections. To connect TeamCity behind a proxy to Amazon EC2 cloud agents, see this section.

TeamCity can use proxy server for certain outgoing HTTP connections made by the TeamCity server to other services like issues trackers, etc.

To point TeamCity to your proxy server: Since TeamCity 2017.1.5 the following server internal properties are available (see the section below for previous version):

The alternative approach, which will work for any TeamCity version, is to pass additional space-delimited additional JVM options to the TeamCity server on the start up:

Configure TeamCity Agent to Use Proxy To Connect to TeamCity Server

This section covers the configuration of a proxy server for TeamCity agent-to-server connections (since TeamCity 2017.1)

On the TeamCity agent side, specify the proxy to connect to TeamCity server using the following properties in the buildAgent.properties file:

Note that the proxy has to be configured not to cache any TeamCity server responses; e.g. if you use Squid, add " cache deny all" line to thesquid.conf file.

Install Multiple Agents on the Same Machine

See the corresponding section under agent installation documentation.

Change Server Port

See corresponding section in server installation instructions.

Test-drive Newer TeamCity Version before Upgrade

It's advised to try a new TeamCity version before upgrading your production server. The usual procedure is to create a copy of your production TeamCity installation, then upgrade it, try the things out, and, when everything is checked, drop the test server and upgrade the main one. When you start the test server, remember to change the Server URL, disable Email and Jabber notifiers as well as other features on the new server.

Create a Copy of TeamCity Server with All Data

In case you want to preserve the original server as well as the copy, make sure to check the licensing considerations.

Create a Server Copy

You can create a copy of the server using TeamCity backup functionality or manually. Manual approach is recommended for the complete server move.

Use TeamCity Backup

1. Create a backup including everything. (You can skip the option to backup build logs is you are moving the artifacts, see below).

2. Install a new TeamCity server of the same version that you are already running. Ensure that: - the appropriate environment is configured (see the notes below) - the server uses its own TeamCity Data Directory and its own database (check config/database.properties in the Data Directory)

3. Restore the backup.

4. Move the artifacts (these are not included into the backup) by moving the content of <TeamCity Data Directory>/system/artifacts directory from the old location to the new one. Since the artifacts can be large in the size, this can take a lot of time, so plan accordingly.

5. Perform the necessary environment transfer.

Copy Manually

If you do not want to use bundled backup functionality or need manual control over the process, here is a description of the general steps one would need to perform to manually create copy of the server:

1. Create a backup so that you can restore it if anything goes wrong,

2. Ensure the server is not running,

3. Either perform clean installation or copy the TeamCity binaries (TeamCity Home Directory) into a new place (the temp and work subdirectories can be omitted during copying). Use exactly the same TeamCity version. If you plan to upgrade after copying, perform the upgrade only after you have the existing version up and running.

4. Copy TeamCity Data Directory. If you do not need the full copy, refer to the items below for options.

   • .BuildServer/config to preserve projects and build configurations settings

   • .BuildServer/lib and .BuildServer/plugins if you have them

   • files from the root of .BuildServer/system if you use internal database and you do not want to perform database move.

   • .BuildServer/system/artifacts (optional) if you want build artifacts and build logs (including tests failure details) preserved on the new server

   • .BuildServer/system/changes (optional) if you want personal changes preserved on the new server

   • .BuildServer/system/pluginData (optional) if you want to preserve state of various plugins, build triggers and settings audit diff

   • .BuildServer/system/caches and .BuildServer/system/caches (optional) are not necessary to copy to the new server, they will be recreated on startup, but can take some time to be rebuilt (expect some slow down).

5. Artifacts directory is usually large and if you need to minimize the downtime of the server in case of the server move, you can use the generic approach for copying the data: use rsync, robocopy or alike tool to copy the data while the original server is running. Repeat the sync run several times until the amount of data synced reduces. Run the final sync after the original server shut down. Alternative solution for the server move is to make the old data artifacts directory accessible to the new server and configure it as second location of artifacts. Then copy the files over from this second location to the main one while the server is running, restart the server after copying completion.

6. Create copy of the database that your TeamCity installation is using in new schema or new database server. This can be done with database-specific tools or with the bundled maintainDB tool by backing up database data and then restoring it.

7. Configure new TeamCity installation to use proper TeamCity Data Directory and database (.BuildServer/config/database.properties points to a copy of the database)

8. Perform the necessary environment transfer.

Environment transferring

Consider transferring relevant environment if it was specially modified for an existing TeamCity installation. This might include:

• use the appropriate OS user account for running the TeamCity server process with properly configured settings, global and file system permissions

• use the same TeamCity process launching options, specifically check/copy environment variables starting with TEAMCITY_

• ensure any files/settings that were configured in the TeamCity web UI with absolute paths are accessible

• if relying on the OS-level user/machine settings like default ssh keys, cached VCS access credentials, transfer them as well

• consider replicating any special settings or exceptions related to the machine in the network configuration, etc.

• If the TeamCity installation was patched in any way (GrrovyPlug plugin, native driver for MS SQL Server integrated security authentication), apply the same modifications to the installation copy

• if you run TeamCity with the OS startup (e.g. Windows service), make sure the same configuration is performed on the new machine

• review and tranfer settings in the <TeamCity home directory>\conf\ teamcity-startup.properties file

• consider any custom settings in <TeamCity home directory>\conf\server.xml

copy_server_licenseLicensing issues

A single TeamCity license cannot be used on two running servers at the same time.

• A copy of the server created for redundancy/backup purposes can use the same license as only one of the servers will be running at a time.

• A copy of the server created for testing purposes requires an additional license. You can get the time-limited TeamCity evaluation license once from the official TeamCity download page. If you need an extension of the license or you have already evaluated the same TeamCity version, please contact our sales department.

• A copy of the server intended to run at the same time as the main one regularly/for production purposes requires a separate license.

Copied Server Checklist

If you are creating a copy (as opposed to moving the server this way), it is important to go through the checklist below:

• ensure the new server is configured to use another data directory and another database than the original server; check also "Artifact directories" setting on server's Global Settings;

• change server unique id by removing "uuid" attribute from XML of <TeamCity Data Directory>\config\main-config.xml file before the first start;

• ensure the same license keys are not used on several servers (more on licensing);

• update Server URL on Administration | Global Settings page to the actual URL of the server;

• check that you can successfully authenticate on the new server, use super user access if necessary;

• check that VCS servers, issue tracker servers, email and Jabber server and other server-accessed systems are accessible;

• check that any systems configured to push events to TeamCity server (like VCS hooks, automated build triggering, monitors, etc.) are updated to know about the new server;

• review the list of installed plugins to determine if their settings need changes;

• install new agents (or select some from the existing ones) and configure them to connect to the new server (using the new server URL);

• check that clients reading from the server (downloading artifact, using server's REST API, NuGet feed, etc.) are reconfigured, if necessary.

If you are creating a test server, you need to ensure that the users and production systems are not affected. Typically, this means you need to:

• disable Email, Jabber (in the "Administration > Notifier" sections) and possibly also custom notifiers or change their settings to prevent the new server from sending out notifications;

• disable email verification (in the "Administration > Authentication" section);

• be sure not to run any builds which change (e.g. deploy to) production environments. This also typically includes Maven builds deploying to non-local repositories. You can prevent any builds from starting by pausing the build queue;

• disable cloud integration (so that it does not interfere with the main server);

• disable external artifact storage (as otherwise running/deleting builds and server cleanup will affect the storage which might be used by the production server);

• disable Git registry cleanup (or just disable cleanup on the server);

• disable Commit Status Publishing;

• disable any plugins which push data into other non-copied systems based on the TeamCity events;

• disable functionality to store project settings in VCS: set teamcity.versionedSettings.enabled=false internal property;

• consider significantly increasing VCS checking for changes interval (server-wide default and overridden in the VCS roots) or changing settings of the VCS roots to prevent them from contacting production servers. Since TeamCity 10.0.3, see also TW-47324.

See also the section below on moving the server from one machine to another.

Move TeamCity Projects from One Server to Another

If you need to move data to a fresh server without existing data, it is recommended to move the server or copy it and then delete the data which is not necessary on the new server.

If you need to join the data with already existing data on the new server, there is a dedicated feature to move projects with most of the associated data from one server to another: Projects Import.

Since TeamCity 8.0 it is possible to move settings of a project or a build configuration to another server with simple file copying. For earlier TeamCity versions see the comment.

The two TeamCity servers (source and target) should be of exactly the same version (same build).

All the identifiers throughout all the projects, build configurations and VCS roots of both servers should be unique. If they are not, you can change them via web UI. If entities with the same id are present on different servers, the entities are assumed to be the same. For example this is useful for having global set of VCS roots on all the servers.

To move settings of the project and all its build configuration from one server to another:

From theTeamCity Data Directory, copy the directories of corresponding projects (.BuildServer\config\projects\<id>) and all its parent projects to .BuildServer\config\projects of the target server. This moves project settings, build configuration settings, VCS roots defined in the projects preserving the links between them. If there are same-named files on the target server as those copied, this can happen in case of a) id match: same entities already exist on the target server, in which case the clashing files can be excluded from copying, or b) id clash: different entities happen to have same ids. In this case it should be resolved either by changing entity id on the source or target server to fulfill the uniqueness requirement.

The set of parent projects is to be identifiedmanually based on the web UI or the directory names on disk (which be default will have the same prefix).

Note: It might make sense to keep the settings of the root project synchronized between all the servers (by synchronizing content of .BuildServer\config\projects_Root directory). For example, this will ensure same settings for the default cleanup policy on all the servers.

Further steps after projects copying might be:

• delete unused data in the copied parent projects (if any) on the target server

• use "server health" reports to identify duplicate VCS roots appeared in result of copying, if any

• archive the projects on the source server and adjust cleanup rules (to be able to see build's history, if necessary)

What is not copied by the approach above:

• pausing comment and user of the paused build configurations

• archiving user of the archived projects

• global server settings (e.g. Maven settings.xml profiles, tools (e.g. handle.exe), external change viewers, build queue priorities, issue trackers). These are stored under various files under .BuildServer\config directory and should be synchronized either on the file level or by configuring the same settings in the server administration UI.

• project association with agent pools

• templates from other projects which are not parents of the copied one. This configuration is actually deprecated in TeamCity 8.0 and is only supported as legacy. Templates used in several projects should be moved to the common parent project or root project.

• no data configured for the agents (build configurations allowed to run on the agent).

• no user-related or user group-related settings (like roles and notification rules)

• no state-related data like mutes and investigations, etc.

Move TeamCity Installation to a New Machine

If you need to move an existing TeamCity installation to new hardware or a clean OS, you can install the same TeamCity version on the new machine, stop the old server, connect the new server to the same TeamCity Data Directory and make sure the server uses the same environment. Alternatively, you can follow the instructions on copying the server from one machine to another.

After the move, make the clients use the new server address, if changed.

You can use the existing license keys when you move the server from one machine to another (as long as there are no two servers running at the same time). As license keys are stored under < >, you transfer the license keys with all the other TeamCity settings data.

It is usually advised not to combine TeamCity update with any other actions, like environment or hardware changes, and perform the changes one at a time so that, if something goes wrong, the cause can be easily tracked.

Switching from one server to another Please note that < > and database should be used by a single TeamCity instance at any given moment. If you configured a new TeamCity instance to use the same data, please ensure you shutdown and disable the old TeamCity instance before starting the new one.

Generally it is recommended to use a domain name to access the server (in the agent configuration and when users access the TeamCity web UI). This way you can update the DNS entry to make the address resolve to the IP address of the new server and after all cached DNS results expire, all clients will automatically use the new server. You might need to reduce the DNS server cache/lease time in advance before the change to make the clients "understand" the change fast.

However, if you need to use another server domain address, you will need to:

• Switch agents to the new URL (requires updating the serverUrl property in buildAgent.properties on each agent). If you want to install agents anew but preserve agent's name and authentication status, you can install a new agent and copy the conf\ buildAgent.properties file from an old agent (checking that any paths in it are updated accordingly).

• Upon the new server startup, remember to update the Server URL on Administration | Global Settings page.

• Notify all TeamCity users on the new address

• Consider updating settings of external services if they depend on the request originating address

Move TeamCity Agent to a New Machine

Apart from the binaries, TeamCity agent installation stores its configuration and data left from the builds it run. Usually the data from the previous builds makes preparation for the future builds a bit faster, but it can be deleted if necessary. The configuration is stored under conf and launcher\conf directories. The data collected by previous build is stored under work and system directories.

The most simple way to move agent installation into a new machine or new location is to:

• stop existing agent

• install a new agent on the new machine

• copy conf/buildAgent.properties from the old installation to a new one

• start the new agent.

With these steps the agent will be recognized by TeamCity server as the same and will perform clean checkout for all the builds.

Please also review the section for a list of directories that can be deleted without affecting builds consistency.

Share the Build number for Builds in a Chain Build

A build number can be shared for builds connected by a snapshot dependency or an artifact dependency using a reference to the following dependency property: %dep.<btID>.system.build.number%.

For example, you have build configurations A and B that you want to build in sync: use the same sources and take the same build number. Do the following:

1. Create build configuration C, then snapshot dependencies: A on C and B on C.

2. Set the Build number format in A and B to:

   %dep.<btID>.system.build.number%

   Where <btID> is the ID of the build configuration C. The approach works best when builds reuse is turned off via the Snapshot Dependencies snapshot dependency option set to off.

Read more about dependency properties.

Please watch/comment the issue related to sharing a build number TW-7745.

Make Temporary Build Files Erased between the Builds

Update your build script to use path stored in ${teamcity.build.tempDir} (Ant's style name) property as the temp directory. TeamCity agent creates the directory before the build and deletes it right after the build.

Clear Build Queue if It Has Too Many Builds due to a Configuration Error

Try pausing the build configuration that has the builds queued. On build configuration pausing all its builds are removed form the queue. Also there is an ability to delete many builds from the build queue in a single dialog.

Automatically create or change TeamCity build configuration settings

If you need a level of automation and web administration UI does not suite your needs, there several possibilities:

• use REST API

• change configuration files directly on disk (see more at TeamCity Data Directory)

• write a TeamCity Java plugin that will perform the tasks using open API.

Attach Cucumber Reporter to Ant Build

If you use Cucumber for Java applications testing you should run cucumber with --expand and special --format options. More over you should specify RUBYLIB environment variable pointing on necessary TeamCity Rake Runner ruby scripts:

Please check the RUBYLIB path separator (';' for Windows, ':' for Linux, or '${path.separator}' in ant for safety). If you are launching Cucumber tests using the Rake build language, TC will add all necessary command line parameters and environment variables automatically. This tip works in TeamCity version >= 5.0.

Get Last Successful Build Number

Use URL like this:

The build number will be returned as a plain-text response. For <ID of build configuration>, see Identifier. This functionality is provided by REST API

Set up Deployment for My Application in TeamCity

TeamCity has enough features to handle orchestration part of the deployments with the actual deployment logic configured in the build script / build runner. TeamCity supports a variety of generic build tools, so any specific tool can be run from within TeamCity. To ease specific tool usage, it is possible to wrap it into a meta-runner or write a custom plugin for that.

In general, setup steps for configuring deployments are:

1. Write a build script that will perform the deployment task for the binary files available on the disk. (e.g. use Ant or MSBuild for this. For typical deployment transports use Deployer runners). See also #Integrate with Build and Reporting Tools. You can use Meta-Runner to reuse a script with convenient UI.

2. Create a build configuration in TeamCity that will execute the build script and perform the actual deployment. If the deployment is to be visible or startable only by the limited set of users, place the build configuration in a separate TeamCity project and make sure the users have appropriate permissions in the project.

3. In this build configuration configure artifact dependency on a build configuration that produces binaries that need to be deployed.

4. Configure one of the available triggers in the deploying build configuration if you need the deployment to be triggered automatically (e.g. to deploy last successful of last pinned build), or use "Promote" action in the build that produced the binaries to be deployed.

5. Consider using snapshot dependencies in addition to artifact ones and check Build Chains tab to get the overview of the builds. In this case artifact dependency should use "Build from the same chain" option.

6. If you need to parametrize the deployment (e.g. specify different target machines in different runs), pass parameters to the build script using custom build run dialog. Consider using Typed Parameters to make the custom run dialog easier to use or handle passwords.

7. If the deploying build is triggered manually consider also adding commands in the build script to pin and tag the build being deployed (via sending a REST API request). You can also use a build number from the build that generated the artifact.

Further recommendations:

• Setup a separate build configurations for each target environment

• Use build's Dependencies tab for navigation between build producing the binaries and deploying builds/tasks

• If necessary, use parameter with "prompt" display mode to ask for "confirmation" on running a build

• Change title of the build configuration "Run" button

Related section on the official site: Continuous Deployment with TeamCity

Use an External Tool that My Build Relies on

If you need to use specific external tool to be installed on a build agent to run your builds, you have the following options:

• Install and register the tool in TeamCity:

  1. Install the tool on all the agents that will run the build. This can be done manually or via an automated script. For simple file distribution also see Installing Agent Tools

  2. Add a property into buildAgent.properties file (or add environment variable to the system) with the tool home location as the value.

  3. Add agent requirement for the property in the build configuration.

  4. Use the property in the build script.

• Check in the tool into the version control and use relative paths.

• Add environment preparation stage into the build script to get the tool form elsewhere.

• Create a separate build configuration with a single "fake" build which would contain required files as artifacts, then use artifact dependencies to send files to the target build.

Integrate with Build and Reporting Tools

If you have a build tool or a tool that generates some report/provides code metrics which is not yet supported by TeamCity or any of the plugins, most probably you can use it in TeamCity even without dedicated integration.

The integration tasks involved are collecting the data in the scope of a build and then reporting the data to TeamCity so that they can be presented in the build results or in other ways.

Data collection The easiest way for a start is to modify your build scripts to make use of the selected tool and collect all the required data. If you can run the tool from a command line console, then you can run it in TeamCity with a command line runner. This will give you detection of the messages printed into standard error output. The build can be marked as failed is the exit code is not zero or there is output to standard error via build failure condition. If the tool has launchers for any of the supported build scripting engines like Ant, Maven or MSBuild, then you can use corresponding runner in TeamCity to start the tool. See also #Use an External Tool that My Build Relies on for the recommendations on how to run an external tool.

You can also consider creating a Meta Runner to let the tool have dedicated UI in TeamCity.

For an advanced integration a custom TeamCity plugin can be developed in Java to ease tool configuration and running.

Presenting data in TeamCity The build progress can be reported to TeamCity via service messages and build status text can also be updated.

For testing tools, if they are not yet supported you can report tests progress to TeamCity from the build via test-related service messages or generate one of the supported XML reports in the build and let it be imported via a service message of configured XML Report Processing build feature.

To present the results for a generic report, the approach might be to generate HTML report in the build script, pack it into archive and publish as a build artifact. Then configure a report tab to display the HTML report as a tab on build's results.

A metrics value can be published as TeamCity statistics via service message and then displayed in a custom chart. You can also configure build failure condition based on the metric.

If the tool reports code-attributing information like Inspections or Duplicates, TeamCity-bundled report can be used to display the results. A custom plugin will be necessary to process the tool-specific report into TeamCity-specific data model. Example of this can be found in XML Test Reporting plugin and FXCop plugin (see a link on Open-source Bundled Plugins).

See also #Import coverage results in TeamCity.

For advanced integration, a custom plugin will be necessary to store and present the data as required. See Developing TeamCity Plugins for more information on plugin development.

Restore Just Deleted Project

TeamCity moves deleted projects settings directories (which are named after the project id) to TeamCity Data Directory/config/_trash directory adding ".<internal ID>" suffix to the directories. To restore a project, find the project directory in the _trash directory and move it into regular projects settings directory: <TeamCity Data Directory>/config/projects while removing the ".projectN" suffix from the directory name. You can do this while server is running, it should pick up the restored project automatically.

Note that TeamCity preserves builds history and other data stored in the database for deleted projects/build configurations for 5 days after the deletion time. All the associated data (builds and test history, changes, etc.) is removed during the next clean-up after the configurable (5 days by default) timeout elapses.

Theconfig/_trash directory is not cleaned automatically and can be emptied manually if you are sure you do not need the deleted projects. No server restart is required.

Transfer 3 Default Agents to Another Server

This is not possible.

Each TeamCity server (Professional and Enterprise) allows using 3 or more agents bound to the server without any agent licenses. In case of the Professional server, by default 3 agents are bound to the server instance: users do not pay for these agents, there is no license key for them. In case of the Enterprise server, the number of agents depends on your package and the agents are bound to the server license key.

So, the agents bound to the server cannot be transferred to another server.

If you need more build agents that are included with your TeamCity server, you can purchase additional build agent licenses and connect more agents in addition to those that come bound with the server.

See more on licensing.

Import coverage results in TeamCity

TeamCity comes bundled with IntelliJ IDEA/Emma and, JaCoCo coverage engines for Java and dotCover/NCover/PartCover for .NET. However, there are plenty of other coverage tools out there, like Cobertura and others which are not directly supported by TeamCity.

In order to achieve similar experience with these tools you can:

• publish coverage HTML report as TeamCity artifact: most of the tools produce coverage report in HTML format, you can publish it as artifact and configure report tab to show it in TeamCity. If artifact is published in the root artifact directory and its name is coverage.zip and there is index.html file in it, report tab will be shown automatically. As to running an external tool, check #Integrate with Build and Reporting Tools.

• extract coverage statistics from coverage report and publish statistics values to TeamCity with help of service message: if you do so, you'll see coverage chart on build configuration Statistics tab and also you'll be able to fail a build with the help of a build failure condition on a metric change (for example, you can fail build if the coverage drops).

Recover from "Data format of the data directory (NNN) and the database (MMM) do not match" error

If you get "Data format of the data directory (NNN) and the database (MMM) do not match." error on starting TeamCity, it means either the database or the TeamCity Data Directory were recently changed to an inconsistent state so they cannot be used together. Double-check the database and data directory locations and change them if they are not those where the server used to store the data. If they are right, most probably it means that the server was upgraded with another database or data directory and the consistent upgrade requirement was not met for your main data directory and the database.

To recover from the state you will need backup of the consistent state made prior to the upgrade. You will need to restore that backup, ensure the right locations are used for the data directory and the database and perform the TeamCity upgrade.

Debug a Build on a Specific Agent

In case a build fails on some agent, it is possible to debug it on this very agent to investigate agent-specific issues. Do the following:

1. Go to the Agents page in the TeamCity Web UI and select the agent.

2. Disable the agent to temporarily remove it from the build grid. Add a comment (optional). To enable the agent automatically after a certain time period, check the corresponding box and specify the time.

3. Select the build to debug.

4. Open the Custom Run dialog and specify the following options:

   1. In the Agent drop-down, select the disabled agent.

   2. It is recommended to select the run as Personal Build option to avoid intersection with regular builds.

5. When debugging is complete, enable the agent manually if automatic re-enabling has not been configured.

You can also perform remote debugging of tests on an agent via the IntelliJ IDEA plugin for TeamCity.

Debug a Part of the Build (a build step)

If a build containing several steps fails at a certain step, it is possible to debug the step that breaks. Do the following:

1. Go to the build configuration and disable the build steps up to the one you want to debug.

2. Select the build to debug.

3. Open the Custom Run dialog and select the put the build to the queue top to give you build the priority.

4. When debugging is complete, re-enable the build steps.

Vulnerabilities

This section describes effect and necessary protection steps related to the announced security vulnerabilities.

Heartbleed, ShellShock

TeamCity distributions provided by JetBrains do not contain software/libraries and do not use technologies affected by Heart bleed and Shell shock vulnerabilities. What might still need assessment is the specific TeamCity installation implementation which might use the components behind those provided/recommended by JetBrains and which can be vulnerable to the mentioned exploits.

POODLE

If you configured HTTPS access to the TeamCity server, inspect the solution used for HTTPS as that might be affected (e.g. Tomcat seems to be affected). At this time none of TeamCity distributions include HTTPS access by default and investigating/eliminating HTTPS-related vulnerability is out of scope of TeamCity.

Depending on the settings used, TeamCity server (and agent) can establish HTTPS connections to other servers (e.g. Subversion). Depending on the server settings, those connections might fall back to using SSL 3.0 protocol. The recommended solution is not TeamCity specific and it is to disable SSLv3 on the target SSL-server side.

GHOST

CVE-2015-0235 vulnerability is found in glibc library which is not directly used by TeamCity code. It is used by the Java/JRE used by TeamCity under *nix platforms. As Java is not bundled with TeamCity distributions, you should apply the security measures recommended by the vendor of the Java you use. At this time there are no related Java-specific security advisories released, so updating the OS should be enough to eliminate the risk of the vulnerability exploitation.

FREAK

CVE-2015-0204 vulnerability is found in the OpenSSL implementation. TeamCity does not bundle any parts of OpenSSL product and so is not vulnerable. You might still need to review the environment in which the TeamCity server and agents are set up, as well as the tools installed in addition to TeamCity for possible vulnerability mitigation steps.

Apache Struts

CVE-2017-5638 affects Jakarta Multipart parser in Apache Struts. CVE-2016-1181 also affects multipart requests processing in some older versions of Apache Struts.

TeamCity bundles IntelliJ IDEA which contains jars from both: Apache Struts 1.x and Apache Struts 2.x. These jars are only used by IntelliJ IDEA Struts plugin when IntelliJ IDEA collects inspections for a project on a TeamCity agent.

But under no circumstances these versions of Apache Struts are used to handle any HTTP requests. Thus neither TeamCity server, not TeamCity agent are affected by these vulnerabilities.

Tomcat Under Windows

Based on the wording of the description of CVE-2017-12615, CVE-2017-12616 and CVE-2017-12617 TeamCity server installed under Windows is a potential subject for the attack. However, our analysis of the vulnerabilities indicates that these potential vulnerabilities cannot be exploited in the default TeamCity installation as the related configuration of Tomcat is inactive in all the TeamCity versions. If necessary, Tomcat bundled with TeamCity can be upgraded to the version 7.0.82 which also removes the vulnerability form the Tomcat code.

Tomcat CVE-2018-8037

TeamCity version 2018.1 is not vulnerable to the issue as it was identified and addressed in the TeamCity codebase before the official Tomcat announcement (actually, the issue was found in a TeamCity installation and we worked with the Tomcat team on fixing it). Earlier TeamCity versions are vulnerable, so upgrading to TeamCity 2018.1+ is necessary.

Watch Several TeamCity Servers with Windows Tray Notifier

TeamCity Tray Notifier is used normally to watch builds and receive notifications from a single TeamCity server. However, if you have more than one TeamCity server and want to monitor them with Windows Tray Notifier simultaneously, you need to start a separate instance of Tray Notifier for each of the servers from the command line with the /allowMultiple option:

• From the TeamCity Tray Notifier installation folder (by default, it's C:\Program Files\JetBrains\TeamCity) run the following command:

  JetBrains.TrayNotifier.exe /allowMultiple

  Optionally, for each of the Tray Notifier instances you can explicitly specify the URL of the server to connect using the /server option. Otherwise, for each further tray notifier instance you will need to log out and change the server's URL via the UI.

  JetBrains.TrayNotifier.exe /allowMultiple /server:http://myTeamCityServer

See also details in the issue tracker.

Personal User Data Processing

In relation to the TeamCity product, JetBrains does not collect any personal data of the on-premises TeamCity installation users. The related documents governing relationship of customers with JetBrains are available on the official web site: privacy policy, terms of purchase, TeamCity license agreement.

The notes below can be useful when assessing how your usage of TeamCity complies with the General Data Protection Regulation (GDPR) (EU) 2016/679 regulation. These notes are meant to address the most basic questions and can serve as an input to the assessment of your specific TeamCity installation. The notes are based on TeamCity 2017.2.4 which is actual at the moment of GDPR enforcement date. Please update your TeamCity instance at least to the version as previous versions might contain issues not in line with the notes below.

TeamCity and Users' Personal Data

The most important user-related data stored by TeamCity is:

• full name and username - stored in the database and shown on the user's profile and whenever the user is referenced. When a user triggers a build, these are also stored in the build's parameters and passed into the build

• user's email - stored in the database and shown on the user's profile, used to send out notifications

• IP address of the clients accessing the server - can appear in the internal logs

TeamCity internal logs can also record some unstructured user-related information (e.g. submitted by the user or sent by the browser with the HTTP requests, retrieved according to the configured settings from the users source like LDAP)

Deleting the User Data

When you want to delete personal data of a specific user, the best way to do it is to delete the user in TeamCity. This way all the references to the user will continue to store the numeric user id, while all the other user information will not be stored anymore. Note that Audit records will mention internal numeric user id after the user deletion.

If the user triggered any builds (i.e. had the "Run build" permission in any of the projects which are still present on the server), the user's username and full name were be recorded in the build's " teamcity.build.triggeredBy" parameters as text values as those were part of the build's "environment". If you need to remove those, you can either delete the related builds (and all the builds which artifact- or snapshot-depend on them), or delete parameters of those affected builds (the parameters are stored in archived files under <TeamCity Data directory>\system\artifacts***\.teamcity\properties directories).

After the user deletion and other data cleaning, make sure to reset search index to prune possibly cached data of the deleted user from the search index.

If user had "Edit project" permission, the full name / username can appear in:

• some audit entries (saved with TeamCity versions before 2017.2.1) - TW-52215

• some build logs in "Wait for pending persist tasks to complete" build log line (saved with TeamCity versions before 2017.2.1) - TW-52872

• commit comments in the repository storing versioned settings store name of the user doing the change in UI

VCS usernames i n VCS-related data :

• in VCS changes visible in UI or stored in the database

• in the local .git repository clones on the server and agents

Username can also appear in access credentials configured in different integrations like VCS roots, issue tracker, database access, etc. (these are stored in the the settings files and audit diff files in the TeamCity Data Directory and VCS roots usernames are also stored in the database for the current and previous versions of the VCS roots)

To ensure user's details are not stored by TeamCity you might want to to check the TeamCity-backing storage that no occurrences of the data are stored: the database, Data Directory and the TeamCity home directory (logs, and memory dumps which are regularly placed under the "bin" directory).

User Agreement

If you want the users to accept a special agreement before using your TeamCity instance, you can install a dedicated plugin developed by JetBrains for this purpose. Refer to the plugin's documentation for more details.

Encryption

If you want to encrypt the data used by TeamCity, it is recommended to use generic, non-TeamCity-specific tools for this as TeamCity does not provide dedicated functionality. TeamCity stores the data in the SQL database and on the file system. You can configure the database to store the data in encrypted form and use secure JDBC-backed connection to the database (configured in the database.properties). Also, you can configure encryption on the disk storage on the OS level.

Logs and Debugging Data

If you want to ensure that you do not store the internal TeamCity logs for more than a limited amount of days, you can configure internal logging to rotate the log files each day and limit the number of files to keep. TeamCity agents generally do not operate with any user-related data in a structural way, but if you need to ensure the logs are regularly rotated on the agent, you will need to configure agent logging the same way. Per-day rotation can be configured by adding <param name="rotateOnDayChange" value="true"/> line within all required<appender name="..." class="jetbrains.buildServer.util.TCRollingFileAppender"> appenders. This change should be done to the default conf\teamcity-server-log4j.xml and also logging presets stored under <TeamCity Data Directory>\config\_logging. TeamCity can also store diagnostics data like thread dumps which can record user-related data in unstructured way. It is recommended to review the content of the <TeamCity Home>\logs directory regularly and ensure that no old files are preserved in there. Also, the extra logs should be deleted after logging customization sessions like collecting debug logs, etc. There is a known issue that logs\catalina.outfile if not rotated automatically at all. It is recommended to establish an automatic procedure to rotate the file regularly.

Customizations

These notes only address bundled TeamCity functionality with the most common documented settings. You should assess your specific TeamCity installation considering customizations like the configured build scripts, installed plugins, external systems communicating with TeamCity via API, etc.

TeamCity Release Cycle

The information below can be used for reference purposes only.

"major" release below means any release with a change in first or second version number (e.g. X in X.X.Z) "bugfix" release means releases with a change in the third version number (e.g. Z in X.X.Z)

Release stages that we generally have are: Available under EAP (Early Access Program) - usually available only for major releases, starts several months after previous major release and usually months before the next major release. Typically new EAP releases are published on monthly or bi-monthly basis. General Availability - as a rule, there is a major release each 8 months. There are multiple bugfix releases following the major release. Bugfix releases and support patches for critical issues (if applicable) are provided until "End of Sale" of the release. End of Sale - occurs with the release of a new major version. After this time no bugfix updates or patches are usually provided (Exceptions are critical issues without a workaround which at the same time allow for relatively simple fix and inability for the customer to upgrade for an important reason). Only limited support is provided for these versions. End of Support - occurs with the release of two newer major versions. At this point we stop providing regular technical support for the release.

The dates of previous releases and the sequence of TeamCity versions are listed on the Previous Releases Downloads page.