How To...

In this section:

Integrate with an issue tracker

Dedicated support for YouTrack, Jira, Bugzilla. You can also turn any issue tracker issue ID references in change comments into links. Please see Mapping External Links in Comments for configuration instructions.

Share the build number for builds in a chain build

Suppose you have build configurations A and B that you want to build in sync: use same sources and take the same build number.
Solution:
Create a build configuration C and create snapshot dependencies A on C and B on C. Then set the Build number format in A and B to:

Where <btID> is the internal ID of the build configuration C. Please refer to the Build Configuration page for description of how to determine build configuration ID.

More on dependency properties.

We plan to provide more option on build number sharing. Please watch/comment on TW-7745.

Use an external tool that my build relies on

Assume, to run a build you need to use specific external tool to be installed on a build agent. To solve the problem, you have the following options:

• Check in the tool into the version control and use relative paths.
• 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.
• Install and register the tool in TeamCity:
  1. Install the tool on all the agents that will run the build.
  2. Add env. or system. property into buildAgent.properties file (or add environment variable to the system).
  3. Add agent requirement for the property in the build configuration.
  4. Use the property in the build script.
• Add environment preparation stage into the build script to get the tool form elsewhere.

Install Multiple Agents on the Same Machine

If you want to install several TeamCity build agents on the same machine, please consider the following:

• TeamCity will work with the agents the same as if they are installed on different machines
• The agents builds running on the agents should not conflict by any resource (common disk directories, OS processes, OS temp directories)
• Depending on the hardware and the builds you may experience degraded builds performance. e.g. ensure there are no disk, memory, CPU bottlenecks when several builds are run at the same time.

For installation instructions, refer to Setting up and Running Additional Build Agents.

Change Server Port

See corresponding section in server installation instructions.

Make temporary build files erased between the build

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.

Retrieve Administrator password

On the first start TeamCity displays Administrator Setup page. TeamCity installation should always have a user with System Administrator role in the current authentication scheme.

In rare cases on user authorization scheme switch there can be no System Administrator on the system. In this case you may setup one as follows:

1. access directly the URL: http://<your_TeamCity_server>/setupAdmin.html
2. create new account (it should not match any existing user account in the system) for the System Administrator role.

If you forgot Administrator password and use internal database, you can reset the password using the instructions.

Ho do I clear build queue if it got 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.
Since TeamCity 5.1 there is an ability to delete many builds from the build queue in a single dialog.

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.

In situations, when 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:

• navigate to TeamCity Tray notifier installation folder (by default, it's C:\Program Files\JetBrains\TeamCity and run the command:
  Optionally, for each of the Tray Notifier instances you can specify explicitly the URL of the the server to connect to with the /server option. Otherwise, for each further tray notifier instance you will need to log out and change server's URL via UI.

See also details in the issue tracker.

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 requirement for additional CPU time (but it can usually be neglected comparing to the build process CPU requirements) and additional memory: about 150Mb. Although, you can run build agent on the same machine as the TeamCity server, the recommended approach is to use a separate machine (though, it may be virtual) for each build agent.

The server hardware requirements depend on the server load. The load on the server depends significantly on the type of the builds and server usage, so here are only some general guidelines.

As you will probably use external database, you will also decide where the database engine will be running (e.g. same machine, dedicated machine or existing database server). If you choose to run the database engine on the same machine, you should consider hardware requirements with database engine in mind.

If you face some TeamCity-related Performance issues, they should probably be investigated and addressed individually. e.g. if builds generate too much data, server disk system might need upgrade both by size and speed characteristics.

The load on the server depends on:

• the number of build configurations
• the number of builds in the history
• the number of the builds running daily
• the amount of data generated by the builds (size of the build log, number and output size of unit tests, number of inspections and duplicates hits etc.)
• the number of agents and their utilization percentage
• the number of users having TeamCity web pages open
• the number of users logged in from IDE plugin
• the number and type of VCS roots as well as 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.
• the number of changes detected by TeamCity per day in all the VCS roots

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

• 60 projects and 300 build configurations, (with one forth being active and running regularly)
• more then 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 then 150 changes per day
• the database (MySQL) is running on the same machine, main TeamCity process has -Xmx1100m -XX:MaxPermSize=120m JVM settings.

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.

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 and add more projects to the server gradually, monitoring the performance characteristics and deciding on necessary hardware or software improvements. Anyway, best administration practices are recommended like keeping adequate disk defragmentation level, etc.

Setup TeamCity in Replication/Clustering Environment

TeamCity does not provide specific support for any of replication/high availability or clustering solutions.

When setting up TeamCity in a replication environment please note that TeamCity uses both database and file storage to save data. 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 disk and database that TeamCity uses should remain in a consistent state and thus should be replicated together.

Only single TeamCity server instance should use database and data directory at any time.

Move TeamCity projects from one server to another.

Generally, moving projects to a server that already have projects/build configurations configured is not supported. For addressing simple cases manually, please see a comment.

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 are two possibilities:

• 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:

If you are launching Cucumber tests using Rake build language TC will add all necessary cmdline parameters and env. variables automatically.
P.S: 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 <internal ID of build configuration>, see Build Configuration#Build Configuration ID.
This functionality is provided by REST API

Move TeamCity installation to a new machine

If you need to move existing TeamCity installation to a new hardware or clean OS, you will basically need to:

• create a backup
• transfer/make accessible TeamCity data (TeamCity Data Directory and database)
• either perform clean installation or move TeamCity binaries into new place
• transfer relevant environment if it was specially modified for existing TeamCity installation. This might include:
  • configure TeamCity to use proper TeamCity Data Directory and database
  • use the same TeamCity process launching options
  • use appropriate OS user account for running TeamCity server process with appropriately configured settings, global and filesystem permissions
  • transfer OS security settings if required
  • ensure any files/settings that were configured in TeamCity web UI are accessible; put necessary libraries/files inside TeamCity installation if they were put there earlier)

If server address is changed, you will also need:

• Switch agents to new URL (requires updating serverUrl property in buildAgent.properties on each agent).
• Upon new server startup do not forget to update Server URL on Server configuration administration page.

Please note that TeamCity Data Directory and database should be used by a single TeamCity instance at any given moment. If you configured new TeamCity instance to use the same data, please ensure you shutdown and disable old TeamCity instance before staring a new one.

After new server start it usually makes sense to check that email, jabber and VCS servers are accessible from the new machine.

A usual advice is 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.

Test-drive Newer TeamCity version before upgrade

It's advised to try new TeamCity version before upgrading your production server. Usual procedure is to create a copy of your production TeamCity installation, try the things out and when everything is checked, dump the test server and upgrade the main one.
Here is a description of general steps you will usually need to make to create copy of the server:

1. create a backup
2. copy TeamCity data (TeamCity Data Directory
   • .BuildServer/config to preserve projects and build configurations settings
   • files from the root of .BuildServer/system (most importantly, version.dat
   • .BuildServer/system/messages if you want build logs (including tests failure details) preserved on the new server
   • .BuildServer/system/artifacts if you want build artifacts preserved on the new server
   • .BuildServer/system/changes if you want personal changes preserved on the new server
   • .BuildServer/system/caches and .BuildServer/system/caches are not necessary to copy to the new server
   • .BuildServer/lib and .BuildServer/plugins is you have them
3. create copy of database that your TeamCity installation is using
4. doublecheck that the new TeamCity installation is configured to use copy of .BuildServer and .BuildServer/config/database.properties points to a copy of the database
5. run new TeamCity server
6. upon new server startup do not forget to update Server URL on Server configuration administration page. You will also probably need to modify Email and Jabber notification sending settings to prevent new server from sending out notifications
7. start new agents and configure them to connect to the new server (using new server URL)

Note: if you want to do a quick check and do not preserve builds history on the new server you can skip all but the first two items of the step 2 and step 3.

How do I chose 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 (e.g. integration with Microsoft TFS and VSS will work only under MS 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 chose to install 64 bit OS, TeamCity can run under 64 bit JDK (both server and agent).
However, unless you need to provide more then 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.

How do I setup deployment for my application in TeamCity

1. Write a build script that will perform the deployment task for the binary files available on the disk. (e.g. use Ant for this)
2. Create a build configuration in TeamCity that will execute the build script.
3. In this build configuration configure artifact dependency on a build that produces binaries that need to be deployed
4. Configure one of the available triggers 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 produces the binaries that need to be deployed.