- 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: See a note on memory usage. Consider also that required memory may depend on the JVM used (32 bit or 64 bit). 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) and , 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).
- 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.
- 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
- 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
Allocating 1 GB for the redo log (see the table below) and undo files is sufficient in most cases.
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 only supports a single instance of the main server, but it is possible to add read-only 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.
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.
- 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
otherwise Referer header can be not present and e.g. build artifacts protection will not work
- 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.propertiesfile 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 the All 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
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.
When using Apache, make sure to use the Dedicated "Connector" node approach for configuring TeamCity server.
For the NGINX configuration below, use the "RemoteIpValve" Approach for configuring TeamCity server.
# For HTTP protocol ## The domain name or the IP address of the proxy host and the port: teamcity.http.proxyHost=proxy.domain.com teamcity.http.proxyPort=8080 ## The hosts that should be accessed without going through the proxy, usually internal hosts. Provide a list of hosts, separated by the '|' character. The wildcard '*' can be used: teamcity.http.nonProxyHosts=localhost|*.mydomain.com) ## For an authenticated proxy add the following properties: ### Authentication type. "basic" and "ntlm" values are supported. The default is basic. teamcity.http.proxyAuthenticationType=basic ### Login and Password for the proxy: teamcity.http.proxyLogin=username teamcity.http.proxyPassword=password # For HTTPS protocol ## The domain name or the IP address of the proxy host and the port: teamcity.https.proxyHost=proxy.domain.com teamcity.https.proxyPort=8080 ## The hosts that should be accessed without going through the proxy, usually internal hosts. Provide a list of hosts, separated by the '|' character. The wildcard '*' can be used: teamcity.https.nonProxyHosts=localhost|*.mydomain.com ## For an authenticated proxy add the following properties: ### Authentication type. "basic" and "ntlm" values are supported. The default is basic. teamcity.https.proxyAuthenticationType=basic ### Login and Password for the proxy: teamcity.https.proxyLogin=login teamcity.https.proxyPassword=password
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.
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
- Create a backup including everything. (You can skip the option to backup build logs is you are moving the artifacts, see below).
- Install a new TeamCity server of the same version that you are already runnningrunning. 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.propertiesin the Data Directory)
- Restore the backup.
- Move the artifacts (these are not included into the backup) by moving the content of
<TeamCity Data Directory>/system/artifactsdirectory 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.
- Perform the necessary environment transfer.
The new server won't get build artifacts and some other data. If you need them, you will need to copy appropriate directories (e.g. the entire "artifacts" directory) from .BuildServer/system from the In order to ensure complete server transfer, it is recommended to copy the entire content of the TeamCity Data Directory from the original to the copied server. Make sure to finish copying over the artifacts It is recommended to complete the copying before starting the new server.
- Create a backup so that you can restore it if anything goes wrong,
- Ensure the server is not running,
- Either perform clean installation or copy the TeamCity binaries (TeamCity Home Directory) into a new place (the
worksubdirectories 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.
- Copy TeamCity Data Directory. If you do not need the full copy, refer to the items below for options.
.BuildServer/configto preserve projects and build configurations settings
.BuildServer/pluginsif you have them
- files from the root of
.BuildServer/systemif 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(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).
- 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.
- 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.
- Configure new TeamCity installation to use proper TeamCity Data Directory and database (
.BuildServer/config/database.propertiespoints to a copy of the database)
- Perform the necessary environment transfer.
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.
- 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.
See also the section below on moving the server from one machine to another.
If you need to join the data with already existing setdata 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.
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
<TeamCity Data Directory
>, you transfer the license keys with all the other TeamCity settings data.
- 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.
- 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.
- In this build configuration configure artifact dependency on a build configuration that produces binaries that need to be deployed.
- 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.
- 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.
- 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.
- 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.
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 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.
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.
- 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.zipand there is
index.htmlfile 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).