In this section:
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:
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.
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:
The load on the server depends on:
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 multicore 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:
-Xmx1100m JVM 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:
-Xmx3700m x64 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#Estimating EC2 Costs
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.
The latest TeamCity version is known to work well with up to 300 build agents (300 concurrently running builds actively logging build run-time data). In synthetic tests the server was functioning OK with as many as 500 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 logs (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.
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.
Other options (less recommended): Try using the http://<your_TeamCity_server>/setupAdmin.html URL to setup an administrator account - the page is available if there is no user account with the System Administrator role in the current authentication scheme. If you forgot the Administrator password and your TeamCity uses an internal database, you can reset the password using the instructions: https://confluence.jetbrains.com/display/TCD8/Changing+user+password+with+default+authentication+scheme. There are also instructions ( http://youtrack.jetbrains.net/issue/TW-12317#comment=27-198752 ) to patch roles directly in the database provided by a user. |
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:
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:
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).
Database-specific considerations
The redo log (or a similar entity) naming for different RDBMS:
RDBMS | Log name |
|---|---|
Oracle | Redo Log |
MS SQL Server | Transaction Log |
PostgreSQL | WAL (write ahead log) |
MySQL + InnoDB and Percona | Redo Log |
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
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.
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:
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.
TeamCity does not provide specific support for full replication/redundancy/high availability (HA) or clustering solutions. The only related ability is to set up separate node for processing running builds.
However, to address fast disaster recovery scenarios, it supports active - failover (hot 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.
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.
Short checklist (see below for full notes)
The following notes are provided only for your reference 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 not vulnerable 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.
Here are some notes on different security-related aspects:
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.
{hidden-data}Security concerns of using cloud integration with a publicly accessible server{hidden-data} |
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.
TeamCity stores user passwords when built-in authentication is used in a salted hashed (MD5) form. Hidden because of https://youtrack.jetbrains.com/issue/TW-41757 |
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:
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:
show table status like '<table name>'; |
or for all tables at once:
show table status like '%'; |
You should ensure max_connections parameter has bigger value than the one specified in TeamCity <TeamCity data directory>/config/database.properties file.
Specifying a too small value in innodb_buffer_pool_size may significantly affect performance:
# InnoDB, unlike MyISAM, uses a buffer pool to cache both indexes and # row data. The bigger you set this the less disk I/O is needed to # access data in tables. On a dedicated database server you may set this # parameter up to 80% of the machine physical memory size. Do not set it # too large, though, because competition of the physical memory may # cause paging in the operating system. Note that on 32bit systems you # might be limited to 2-3.5G of user level memory per process, so do not # set it too high. innodb_buffer_pool_size=2000M |
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 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_log_file_size=1024M |
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.
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:
# If set to 1, InnoDB will flush (fsync) the transaction logs to the # disk at each commit, which offers full ACID behavior. If you are # willing to compromise this safety, and you are running small # transactions, you may set this to 0 or 2 to reduce disk I/O to the # logs. Value 0 means that the log is only written to the log file and # the log file flushed to disk approximately once per second. Value 2 # means the log is written to the log file at each commit, but the log # file is only flushed to disk approximately once per second. innodb_flush_log_at_trx_commit=2 |
Note: it is not important for TeamCity that database offers full ACID behavior, so you can safely change this variable.
Placing the MySQL log files on different disk sometimes helps improving performance. You can read about it in MySQL documentation.
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:
binlog-format=mixed |
To get additional diagnostics data in case of some database-specific errors, grant more permissions for a TeamCity database user via SQL command:
GRANT PROCESS ON *.* TO <teamcity-user-name>; |
internal JetBrains guides on setting MySql replication: https://confluence.jetbrains.com/display/JBINT/Setting+up+MySQL+slave+replication https://confluence.jetbrains.com/display/JBINT/Repairing+broken+MySQL+replication |
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.
The default value of shared_buffers parameter is too small and should be increased:
shared_buffers=512MB |
For write-intensive applications such as TeamCity, it is recommended to change some of the checkpoint-related parameters:
For PostgreSQL 9.5 and later:
max_wal_size = 1500MB checkpoint_completion_target=0.9 |
For versions prior to PostgreSQL 9.5:
checkpoint_segments=32 checkpoint_completion_target=0.9 |
If TeamCity is the only application using the PostgreSQL database, we recommend disabling the synchronous_commit parameter:
synchronous_commit=off |
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.
Consider the example:
TeamCity server is installed at URL (local URL): http://teamcity.local:8111/tc
It 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.
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:
<IfModule mpm_worker_module> ServerLimit 100 StartServers 3 MinSpareThreads 25 MaxSpareThreads 75 ThreadLimit 64 ThreadsPerChild 25 MaxClients 2500 MaxRequestsPerChild 0 </IfModule>
On Windows you may need to increase the ThreadsPerChild value as described in the Apache documentation.
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.
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 /teamcity { # public context (should be the same as internal context)
proxy_pass http://teamcity.local:8111/teamcity; # 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
}
}
} |
{hidden-data}
some more NGINX params which might also relate:
client_header_timeout 10m;
client_body_timeout 10m;
send_timeout 10m;
proxy_max_temp_file_size 10240m;
{hidden-data} |
Make sure to use a performant proxy with due (high) limits on request (upload) and response (download) size and timeouts (idle timeout should be hours to support server-side checkout).
It is recommended to use a proxy capable of working with the WebSocket protocol.
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. Alternatively, the proxy should rewrite local TeamCity server absolute URLs in responses to public URLs, but since there are many locations which can use the URLs, this is usually not feasible at full scale.
Note that whenever the value of the "Host" header is changed by the proxy (while it is recommended to preserve original Host header value), 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.
For a due TeamCity Tomcat configuration, there are two options:
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.
<Connector port="8111" protocol="org.apache.coyote.http11.Http11NioProtocol"
connectionTimeout="60000"
useBodyEncodingForURI="true"
socket.txBufSize="64000"
socket.rxBufSize="64000"
tcpNoDelay="1"
proxyName="teamcity.public"
proxyPort="400"
secure="false"
scheme="http"
/> |
When the public server address is HTTPS, use the secure="true" and scheme="https" attributes.
This approach can be used when the proxy server sets "Host", "X-Forwarded-Proto", "X-Forwarded-Port" request headers to the values of the original URL.
Also, while not critical for the most setups, this can be used to make sure the original client IP is passed correctly to the TeamCity server. This is important for agents using bidirectional communication.
Add the following into the Tomcat main <Host> node of the conf\server.xml file (see also Tomcat doc):
<Valve className="org.apache.catalina.valves.RemoteIpValve" remoteIpHeader="x-forwarded-for" protocolHeader="x-forwarded-proto" portHeader="x-forwarded-port" /> |
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"
{hidden-data}see also comment: [http://youtrack.jetbrains.com/issue/TW-11166#comment=27-331468]{hidden-data} |
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 at your proxy server, you need to pass additional JVM options to the TeamCity server on the start up:
JVM arguments:
-Dproxyset=true -Dhttp.proxyHost=proxy.domain.com -Dhttp.proxyPort=8080 -Dhttp.nonProxyHosts=domain.com -Dhttps.proxyHost=proxy.domain.com -Dhttps.proxyPort=8080 -Dhttps.nonProxyHosts=domain.com |
This section covers the configuration of a proxy server for TeamCity agent-to-server connections (since TeamCity 2017.1)
On the TeamCity side, the proxy can be specified using the following properties in the
|
See the corresponding section under agent installation documentation.
See corresponding section in server installation instructions.
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.
One of the ways to create a copy of the server is to create a backup, then install a new TeamCity server of the same version that you already run, ensure you have appropriate environment configured (see notes below), ensure that the server uses own TeamCity Data Directory and own database and then restore the backup.
This way the new server won't get build artifacts and some other less important data. If you need them, you will need to copy appropriate directories (e.g. entire "artifacts" directory) from .BuildServer/system from the original to the copied server. Make sure to finish copying over the artifacts before starting the new server.
Also consider transferring other settings to the new installation:
<TeamCity home directory>\conf\teamcity-startup.properties fileIf 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:
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.TEAMCITY_..BuildServer/config to preserve projects and build configurations settings.BuildServer/lib and .BuildServer/plugins if you have them.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)..BuildServer/config/database.properties points to a copy of the database)Note: if you want to do a quick check and do not want to preserve builds history on the new server you can skip step 6 (cloning database) and all items of the step 5 marked as optional.
If you are creating a copy (as opposed to moving the server this way), it is important to go through the checklist below:
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 any plugins which push data into other non-copied systems based on TeamCity events (like commit status publishing);
https://youtrack.jetbrains.com/issue/TW-47362 |
disable functionality to store project settings in VCS: set teamcity.versionedSettings.enabled=false internal property;
{hidden-data}related issue: [https://youtrack.jetbrains.com/issue/TW-38304]{hidden-data} |
See also the notes on moving the server from one machine to another.
Licensing issues
You cannot use a single TeamCity license on two running servers at the same time, so to run a copy of TeamCity server you will need another license. Copies of the server created for redundancy/backup purposes can use the same licenses as they only should be running one at a time.
If you are only going to run the server for testing purposes, you can get 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.
If you plan to run the second server at the same time as the main one regularly/for production purposes, you need to purchase separate licenses for the second server.
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 set, 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. 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 ( 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 Further steps after projects copying might be:
What is not copied by the approach above:
|
If you need to move the existing TeamCity installation to a new hardware or clean OS, it is recommended to follow the instructions on copying the server from one machine to another and then switch from the old server to a new one. If you are sure you do not need to preserve the old server, you can perform move operations instead of copying in those instructions.
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 <TeamCity Data Directory>, you transfer the license keys with all the other TeamCity settings data.
It is usually advisec 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 <TeamCity Data Directory > 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:
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).Apart from the binaries, TeamCity agent 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:
conf/buildAgent.properties from the old installation to a new oneWith 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.
{hidden-data}
h3. Integrate with an Issue Tracker
TeamCity comes with dedicated [support|Integrating TeamCity with Issue Tracker] for YouTrack, Jira and Bugzilla.
For any other tracker, you can turn any issue tracker issue ID references in change comments into links. Please see [Mapping External Links in Comments] for configuration instructions.
h3. Integrate with Wiki
You can use [external status widget|Configuring General Settings#addingStatusWidget] to incorporate information about a build status into any HTML page.
For example, to include the status widget into a Confluence page, ensure you have XXX plugin installed that will allow to include HTML snippets into any page and use markup like (do not forget to replace _<values>_:
{code}
{{include-html}}
<style type="text/css">
@import" <TeamCity_server_URL>/css/status/externalStatus.css";
</style>
<script type="text/javascript" src="<TeamCity_server_URL>/externalStatus.html?js=1&buildTypeId=<buildConfigurationId1>&buildTypeId=<buildConfigurationId2>&buildTypeId=<buildConfigurationId3>">
</script>
{{include-html}}
{code}
TeamCity allows user to display information about current status of a build configuration on a Confluence Wiki page (as well as on any other web-page) [via the external status widget|Configuring General Settings#addingStatusWidget].
{note}Please beware that any information about build configuration published with the external status widget is available for *any* viewer of the page where you've integrated the widget.{note}
Please note that to integrate status widget into the Confluence page or another Wiki page you should have a macros or plugin which allows to insert plain HTML code into the page. For example, in Confluence you can use {{include-html}} macro.
{hidden-data} |
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:
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 Do not run new build if there is a suitable one snapshot dependency option set to off.
Read more about dependency properties.
Please watch/comment the issue related to sharing a build number TW-7745.
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.
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.
If you need a level of automation and web administration UI does not suite your needs, there several possibilities:
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:
<target name="features">
<java classname="org.jruby.Main" fork="true" failonerror="true">
<classpath>
<pathelement path="${jruby.home}/lib/jruby.jar"/>
<pathelement path="${jruby.home}/lib/ruby/gems/1.8/gems/jvyaml-0.0.1/lib/jvyamlb.jar"/>
....
</classpath>
<jvmarg value="-Xmx512m"/>
<jvmarg value="-XX:+HeapDumpOnOutOfMemoryError"/>
<jvmarg value="-ea"/>
<jvmarg value="-Djruby.home=${jruby.home}"/>
<arg value="-S"/>
<arg value="cucumber"/>
<arg value="--format"/>
<arg value="Teamcity::Cucumber::Formatter"/>
<arg value="--expand"/>
<arg value="."/>
<env key="RUBYLIB"
value="${agent.home.dir}/plugins/rake-runner/rb/patch/common${path.separator}${agent.home.dir}/plugins/rake-runner/rb/patch/bdd"/>
<env key="TEAMCITY_RAKE_RUNNER_MODE" value="buildserver"/>
</java>
</target>
|
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.
Use URL like this:
http://<your TeamCity server>/app/rest/buildTypes/id:<ID of build configuration>/builds/status:SUCCESS/number |
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
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:
Further recommendations:
Related section on the official site: Continuous Deployment with TeamCity
{hidden-data}
related blog posts:[http://java.dzone.com/articles/automated-deployments-teamcity][http://blog.anthonybaker.me/2013/05/how-to-automate-app-deployment-in_1352.html][http://www.troyhunt.com/2010/11/you-deploying-it-wrong-teamcity_25.html]
{hidden-data} |
If you need to use specific external tool to be installed on a build agent to run your builds, you have the following options:
buildAgent.properties file (or add environment variable to the system) with the tool home location as the value.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.
TeamCity moves settings files of deleted projects under TeamCity Data Directory/config/_trash directory.
To restore project you should find the directory on the server and move it into regular projects settings directory: <TeamCity Data Directory>/config/projects . Also you should remove suffix \.projectN from the directory name.
You can do this while server is running, it should pick up restored project automatically.
Please note that TeamCity preserves builds history and other data stored in the database for deleted projects/build configurations for 24 hours since the deletion time. All the associated data (builds and test history, changes, etc.) is removed during the next cleanup after 24 hours timeout elapses.
The config/_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.
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.
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:
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.You should not publish values CodeCoverageB, CodeCoverageL, CodeCoverageM, CodeCoverageC standing for block/line/method/class coverage percentage. TeamCity will calculate these values using their absolute parts. E.g. CodeCoverageL will be calculated as CodeCoverageAbsLCovered divided by CodeCoverageAbsLTotal. |
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.
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:
You can also perform remote debugging of tests on an agent via the IntelliJ IDEA plugin for TeamCity.
If a build containing several steps fails at a certain step, it is possible to debug the step that breaks. Do the following:
This section describes effect and necessary protection steps related to recently announced security vulnerabilities.
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.
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.
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.
CVE-2015-0204 vulnerability is found in OpenSSL implementation and TeamCity does not bundle any parts of OpenSSL product and so is not vulnerable. You might still need to review the environment in which TeamCity server and agents are installed as well as tools installed in addition to TeamCity for possible vulnerability mitigation steps necessary.
CVE-2017-5638 affects Jakarta Multipart parser in Apache Struts. Since no versions of TeamCity use struts, TeamCity is not affected.
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.
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.
Dates for the previous releases can be seen at Previous Releases Downloads.
{hidden-data}
empty lines to allow proper anchor positioning
Setting up TeamCity for demo mode
- when setting up a build configuration from scratch, consider disabling favorite builds on your user profile if you are not demoing those
- reduce global server checking for changes interval
- reduce build trigger/starting periods (TBD, internal properties)
{hidden-data} |