Blogroll Features How-To's

Deploying TeamCity into AWS using CloudFormation and Fargate

For the good cause, it is sometimes easier to start with TeamCity by deploying it into a cloud service, such as AWS. This allows the users to try TeamCity without the need to prepare the dedicated machine.

For the quick start, it is possible to use CloudFormation template which deploys the minimal setup to AWS. For the agents, TeamCity includes the integration for Amazon EC2 out of the box. However, there is also an alternative way to start the agents as Docker containers at Amazon’s Elastic Container Services platform.

In this article, we’re going to describe how to deploy TeamCity server using the CloudFormation template and how to configure the agents to run on Amazon ECS with Fargate.

Deploying TeamCity server to AWS with CloudFormation template

The official TeamCity CloudFormation template is available to simplify deployment to AWS. The resulting implementation will start a VM with two Docker containers: one for TeamCity server, and the other for the default agent.

DISCLAIMER: The current configuration of the CloudFormation template is not recommended for production setup. The default agent is configured to run on the same machine as the TeamCity server. Instead, it is advised to run the agents separately in order not to consume the machine resources required by the server.

Deploy TeamCity to AWS using CloudFormation template

Once a TeamCity server is deployed, check the Outputs tab for the URL. After the initial configuration steps, it is possible to add more build agents to the server. There are multiple options for TeamCity agents deployment at AWS. In the following, we’ll describe how to deploy the agent to Amazon ECS with Fargate.

AWS Fargate for TeamCity Agents

AWS Fargate is a technology for Amazon ECS that allows us to run containers without having to manage servers. TeamCity agent can be deployed as a container to ECS by using Fargate.

The short-lived container instances at ECS are perfectly suitable for executing build tasks. For TeamCity, it means that it is possible to acquire more resources dynamically. Once more agents are required to process the build queue TeamCity will request a new agent to start via Fargate. The agents can stop once the workload isn’t as high anymore.

To run TeamCity agents at Amazon ECS with Fargate several steps needs to be fulfilled:

  1. Have a running TeamCity server instance
  2. Install the required plugins for TeamCity server
  3. Create task definition for TeamCity agent in Amazon ECS
  4. Create cloud agent profile for the project in TeamCity
  5. Optionally, configure S3 artifact storage for the project in TeamCity

Installing Plugins

The required integration with various AWS services activates by installing the additional plugins to TeamCity server. To make use of AWS Fargate integration in TeamCity the Amazon ECS Support plugin needs to be installed. Also, one might want to consider storing the build artifacts in Amazon S3 as well. AWS S3 Artifact Storage plugin enables the integration.

Once the plugins are installed, we can proceed to the configuration.

Agents Configuration

Create AWS Fargate task definition

TeamCity agent is available as a Docker image via Docker Hub. In the Fargate task definition, it is possible to define a container, referring to that image. Once the server requests for a new agent via Fargate, a new container will start on Amazon ECS.

The important bit is to add SERVER_URL environment variable pointing at the URL of the TeamCity server. The agent will use that variable to connect to the server.

Create Fargate task definition

Create cloud profile for a project in TeamCity

To enable cloud integration in TeamCity one has to create a cloud profile for the desired project. Configuring cloud profile in TeamCity is quite straightforward.

Go to the project settings, the Cloud Profiles tab, click “Create new cloud profile” button and proceed with the configuration. Make sure to select Amazon Elastic Container Service as the cloud type.

It is also important that the selected AWS region in the cloud profile matches the region that you used to create the Fargate task definition.

In order to point the cloud profile at the task definition in Farget we have to add an agent image with the appropriate launch type.

Create Fargate task definition

Artifact Storage Configuration

In TeamCity, a build configuration can expose the resulting artifacts. It is wise to store the artifacts in the external storage. We can use Amazon S3 to save the files. Let’s see how to configure the service for TeamCity.

In the project settings, navigate to the Artifacts Storage Project tab and click the “Add new storage” button. Select “S3 Storage” type and fill in the name, bucket name and press Save. After that, activate this artifact storage in the TeamCity project by clicking the “Make Active” link. The new builds in this project will store artifacts in S3 automatically.

S3 artifact storage configuration


TeamCity was designed as on-premise solution. However, cloud services, such as AWS, simplify the setup if you would like to try TeamCity for your projects. It is easy to start with the CloudFormation template and scale by deploying the agents as Docker containers at Amazon ECS.

image description