How To...

Install Non-Bundled Version of Tomcat

The TeamCity Server distributions include a Tomcat version tested to work fine with the current version. You can use an alternative Tomcat version, but note that other combinations are not guaranteed to work correctly.

To use another version of the Tomcat web server instead of the bundled one, you need to perform the Tomcat upgrade/patch.

When using an .exe distribution of TeamCity, we suggest that you:

• Back up the current TeamCity Home.

• Delete/move from the TeamCity Home directories that are also present in the Tomcat distribution.

• Unpack the Tomcat distribution to the TeamCity Home directory.

• Copy TeamCity-specific files from the previously backed-up/moved directories to the TeamCity Home:

  • files under bin which are not present in the Tomcat distribution

  • review differences between the default Tomcat conf directory and one from TeamCity, update Tomcat files with TeamCity-specific settings (teamcity-* files, and portions of server.xml)

  • delete the default Tomcat webapps/ROOT directory and replace it with the one provided by TeamCity

Autostart TeamCity Server on macOS

Starting up the TeamCity server on macOS is quite similar to starting Tomcat on macOS.

1. Install TeamCity and make sure it works if started from the command line with bin/teamcity-server.sh start. This instruction assumes that TeamCity is installed to /Library/TeamCity.

2. Create the /Library/LaunchDaemons/jetbrains.teamcity.server.plist file with the following content:

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>WorkingDirectory</key> <string>/Library/TeamCity</string> <key>Debug</key> <false/> <key>Label</key> <string>jetbrains.teamcity.server</string> <key>OnDemand</key> <false/> <key>KeepAlive</key> <true/> <key>ProgramArguments</key> <array> <string>/bin/bash</string> <string>--login</string> <string>-c</string> <string>bin/teamcity-server.sh run</string> </array> <key>RunAtLoad</key> <true/> <key>StandardErrorPath</key> <string>logs/launchd.err.log</string> <key>StandardOutPath</key> <string>logs/launchd.out.log</string> </dict> </plist>

3. Test your file by running:

   launchctl load /Library/LaunchDaemons/jetbrains.teamcity.server.plist

   This command should start the TeamCity server (you can see this from logs/teamcity-server.log and in your browser).

4. If you don't want TeamCity to start under the root permissions, specify the UserName key in the .plist file, for example:

   <key>UserName</key> <string>teamcity_user</string>

The TeamCity server will now start automatically when the machine starts. To configure automatic start of a TeamCity build agent, see the dedicated section.

Estimate Number of Required Build Agents

The number of required build agents depends on the server usage pattern, type of builds, team size, commitment of the team to CI process, and so on. In general, the best way is to start with three agents and see how they handle the projects on your server, and then make estimations for the future.

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 (for example, 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.

TeamCity Security Notes

The contents of this section have been moved to the dedicated article.

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.

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; for example, if you use Squid, add "cache deny all" line to the squid.conf file.

Install Multiple Agents on the Same Machine

See the corresponding section under agent installation documentation.

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

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, TeamCity 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

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:

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

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: a. In the Agent drop-down menu, select the disabled agent. b. 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 reenabling 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, reenable the build steps.