In this section:
Configure TeamCity integration with an issue tracker:
Use issue tracker integration:
fixed TW-12308
. TeamCity will transform the issue ID into a link to the corresponding issue, and copy its summary right into the comment.TeamCity treats equally all agents no matter if they are installed on the same or on different machines. However, before installing several TeamCity build agents on the same machine, please consider the following:
After having one agent installed, you can install additional agent by following the regular installation procedure, but make sure that:
work
and temp
directories.name
and ownPort
properties of buildAgent.properties
are unique.If you are installing additional agents as services under Windows, modify the <agent>\launcher\conf\wrapper.conf
: wrapper.console.title
, wrapper.ntservice.name
, wrapper.ntservice.displayname
and wrapper.ntservice.description
properties should have unique values within the computer.
A related feature request in our tracker.
Moreover, make sure you don't have build configurations with absolute checkout directory specified (alternatively, make sure such build configurations have "clean checkout" option enabled and they cannot be run in parallel).
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:
C:\Program Files\JetBrains\TeamCity
run the following command:
JetBrains.TrayNotifier.exe /allowMultiple |
/server
option. Otherwise, for each further tray notifier instance you will need to log out and change server's URL via UI.
JetBrains.TrayNotifier.exe /allowMultiple /server:http://myTeamCityServer |
See also details in the issue tracker.
If you need to move existing TeamCity installation to a new hardware or clean OS, it is recommended to follow 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 the old server data you can probably perform move operations instead of copying.
You can use 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.
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.
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 new TeamCity instance to use the same data, please ensure you shutdown and disable old TeamCity instance before staring a new one.
Generally it is recommended to use a domain name to access the server (in agent configuration and when users access 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 be automatically using the new server.
However, if you need to use another server address, you will need:
serverUrl
property in buildAgent.properties on each agent).Server configuration
administration page.{hidden-data} h3. Integrate with Wiki You can use [external status widget|Enabling the Status Widget for Build Configurations] 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|Enabling the Status Widget for Build Configurations]. {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} |
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:
%dep.<btID>.system.build.number% |
Read more about dependency properties.
We plan to provide more option on build number sharing. Please watch/comment on TW-7745.
If you need to use specific external tool to be installed on a build agent to run your builds, you have the following options:
env.
or system.
property into buildAgent.properties
file (or add environment variable to the system).{hidden-data} h3. Measure Coverage of my .Net Code To measure coverage for your .Net code you can use NCover. See [Lauren Kempe blog post on the matter|http://www.intellij.net/forums/thread.jspa?threadID=277581]. {hidden-data} |
See corresponding section in server installation instructions.
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.
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:
http://<your_TeamCity_server>/setupAdmin.html
If you forgot Administrator password and use internal database, you can reset the password using the instructions.
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.
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, which in its turn depends significantly on the type of the builds and server usage. Consider the following general guidelines.
|
Overview on the TeamCity hardware resources usage:
The load on the server depends on:
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 following setup:
-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.
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
TeamCity does not provide specific support for any of replication/high availability or clustering solutions; however you can replicate the data that TeamCity server uses and prepare to start a new server using the same data if existing server malfunctions.
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.
Please also ensure that the distribution of the backup server is of exactly the same version as the main server.
See also information on switching 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.
If you need a level of automation and web administration UI does not suite your needs, there are two 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/lib/rb/patch/common;${agent.home.dir}/plugins/rake-runner/lib/rb/patch/bdd"/> <env key="TEAMCITY_RAKE_RUNNER_MODE" value="buildserver"/> </java> </target> |
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.
Use URL like this:
http://<your TeamCity server>/app/rest/buildTypes/id:<internal ID of build configuration>/builds/status:SUCCESS/number |
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
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, ensure that the server uses own TeamCity Data Directory and database and then restore the backup.
This way, the backup will not contain:
.BuildServer/system/artifacts
from the original server to the copied server..BuildServer/plugins
- copy the directory if you have it.BuildServer/lib
- copy the directory if you have itIf you do not want to use bundled backup functionality or need manual control over the process, here is a description of the general steps you will usually need to make to 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 existing version up and running..BuildServer/config
to preserve projects and build configurations settings.BuildServer/lib
and .BuildServer/plugins
if you have them.BuildServer/system
(most importantly, version.dat
). The file license.keys
contains license key, and you can copy it only if you make the copy for backup/evaluation purposes..BuildServer/system/messages
(optional) if you want build logs (including tests failure details) preserved on the new server.BuildServer/system/artifacts
(optional) if you want build artifacts preserved on the new server.BuildServer/system/changes
(optional) if you want personal changes preserved on the new server.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.
At this point you should be ready to run the copy TeamCity server.
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.
Server configuration
administration page. You will also probably need to modify Email and Jabber notification sending settings to prevent new server from sending out notificationsIt's advised to try new TeamCity version before upgrading your production server. 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.
You can get an evaluation license for the new server at the official download page.
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 choose 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. See a note on memory configuration.
If you have a tool that generates some report or provides code metrics, you may want to display the data in TeamCity.
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.
For an advanced integration a custom TeamCity plugin can be developed to ease tool configuration and running. See XML Test Reporting and FXCop plugin (see a link on Open-source Bundled Plugins) as an example.
Presenting data in TeamCity
For a report, the most simple approach is 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.
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).
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.