Setting Up TeamCity for Amazon EC2

Last modified: 20 April 2023

TeamCity Amazon EC2 integration allows to configure TeamCity with your Amazon account and then start and stop images with TeamCity agents on-demand based on the queued builds.

For integrations with other cloud solutions, see Cloud-VMWare plugin and Implementing Cloud support.

Understanding Amazon EC2 and ability to perform EC2 tasks is a prerequisite for configuring and using TeamCity Amazon EC2 integration.

Basic TeamCity EC2 setup involves:

  • preparing Amazon EC2 image (AMI) with installed TeamCity agent

  • configuring EC2 integration on TeamCity server

Please ensure that the server URL specified on General Server Configuration page is correct since agents will use it to connect to the server.

Preparing AMI with Installed TeamCity Agent



Here are the requirements for an image that can be used for TeamCity cloud integration:

  • TeamCity agent should be correctly Setting up and Running Additional Build Agents.

  • TeamCity agent should start on machine startup

  • buildAgent.properties can be left "as is". "serverUrl", "name" and "authorizationToken" properties can be empty or set to any value, they are ignored when TeamCity starts the instance.

Provided these requirements are met, usual TeamCity agent installation and Amazon AMI bundling procedures are applicable.

If you need the Setting up and Running Additional Build Agents between the server and the agent machine to be secure, you will need to setup the agent machine to establish a secure tunnel (e.g. VPN) to the server on boot so that TeamCity agent receives data via the secure channel.

Recommended AMI preparation steps:

  1. Choose one of existing AMIs.

  2. Start AMI.

  3. Configure the running instance:

    • Install and configure build agent:

      • Configure server name and agent name in conf/buildAgent.properties — this is optional, if the image will be started by TeamCity, but it is useful to test the agent is configured correctly.

      • It usually makes sense to specify tempDir and workDir in conf/buildAgent.properties to use non-system drive (d: under Windows)

    • Install any additional software necessary for the builds on the machine.

    • Run the agent and check it is working OK and is compatible with all necessary build configurations, etc.

    • Configure system so that agent it is started on machine boot (and make sure TeamCity server is accessible on machine boot).

  4. Test the setup by rebooting machine and checking that the agent connects normally to the server.

  5. Prepare the Image for bundling:

    • Remove any temporary/history information in the system.

    • Stop the agent (under Windows stop the service but leave it in Automatic startup type)

    • Delete content logs and temp directories in agent home (optional)

    • Delete "<Agent Home>/conf/amazon-*" file (optional)

    • Change config/buildAgent.properties to remove properties: name, serverUrl, authorizationToken (optional)

  6. Make AMI from the running instance.

  7. Configure TeamCity EC2 support on TeamCity server.

Agent auto-upgrade Note TeamCity agent auto-upgrades whenever distribution of agent plugins on the server changes (e.g. after TeamCity upgrade). If you want to cut agent startup time, you might want to re-bundle the agent AMI after agent plugins has been auto-updated.

Estimating EC2 Costs



Usual Amazon EC2 pricing applies. Please note that Amazon charges can depend on the specific configuration implemented to deploy TeamCity. We advice you to check your configuration and Amazon account data regularly in order to discover and prevent unexpected charges as early as possible.

Please note that traffic volumes and necessary server and agent machines characteristics depend a big deal on the TeamCity setup and nature of the builds run. See also How To....

Traffic Estimate



Here are some points to help you estimate TeamCity-related traffic:

  • If TeamCity server is not located within the same EC2 region or availability zone that is configured in TeamCity EC2 settings for agents, traffic between the server and agent is subject to usual Amazon EC2 external traffic charges.

  • When estimating traffic please bear in mind that there are lots types of traffic related to TeamCity (see a non-complete list below).

External connections originated by server:

  • VCS servers

  • Email and Jabber servers

  • Maven repositories

Internal connections originated by server:

  • TeamCity agents (checking status, sending commands, retrieving information like thread dumps, etc.)

External connections originated by agent:

  • VCS servers (in case of agent-side checkout)

  • Maven repositories

  • any connections performed from the build process itself

Internal connections originated by agent:

  • TeamCity server (retrieving build sources in case of server-side checkout or personal builds, downloading artifacts, etc.)

Usual connections served by the server:

  • web browsers

  • IDE plugins

Uptime Costs



As Amazon rounds machine uptime to the nearest full hour, please adjust timeout setting on the EC2 image setting on TeamCity cloud integration settings according to your usual builds length.

It is also highly recommended to set execution timeout for all your builds so that a build hanging does not cause prolonged instance running with no payload.