TeamCity 2020.2 Help

Running TeamCity Stack in AWS

You can run the TeamCity stack in AWS using the CloudFormation template. Note that this is an experimental option, which is currently a work in progress.

Stack Overview

The current setup uses 2 subnets, a public and a private one.

  • The private subnet includes all the essential items:
    • ECS cluster of a Amazon ECS Optimized Linux EC2 instance with the official TeamCity server of the specified version from Docker Hub and one TeamCity Build Agent. The official Docker images with the TeamCity server and build agent are used.

    • RDS MySQL database

  • The public subnet includes:
    • Application Load Balancer

    • NAT gateway ensuring the publicly available IPs

Both subnets are placed into a Virtual Private Cloud (VPC) which is completely secure. The database allows only internal connections within the VPC and its possible to connect to the Server via HTTP(s) or SSH only.


To create a TeamCity stack and connect to it, you will need:

  • EC2 KeyPair in the same region as the TeamCity stack

  • Installed SSH client to connect to the TeamCity server and view the logs

  • IAM permissions to create the service-linked role and apply a policy to it for the IAM entity creating the stack

Using Template

1. On the Select Template page, select the default TeamCity Template and click Next.

2. Specify the stack name and parameters provided by the template:

Template Parameters




The name for your TeamCity server, set to test by default.

TeamCity Version

By default, the template will create a TeamCity installation of the latest version. You can also specify the exact version number here, for example, 2017.1.5, 2017.2.

Internet-Facing Stack

By default, set to false. This setting affects the Application Load Balancer: by default it has no public IP address and only receives traffic inside VPC. To create a publicly available TeamCity instance, set it to true.

EC2 KeyPair (required)

Specify an existing EC2 KeyPair for SSH access to the TeamCity Server EC2 instance. If you fail to provide the key pair, the stack creation will fail with the following error: "Template validation error: Parameter 'KeyName' must match pattern .+"

SSL Certificate Domain

Optional. If you are a domain owner, you can specify the domain here and get the certificate that will be automatically registered in your load balancer. Your stack creation will be paused until you validate your email.

EC2 instance Type

Specify the type of instance for the TeamCity server

Container CPUContainer CPU in virtual CPU units
Container Memory

Set to 3700 MiB by default.

RDS Database Instance Type

Specify the type for the RDS MySQL instance used as the external database for TeamCity. Default: db.t2.medium.

TeamCity Database Password (required)

Specify any password for the TeamCity database

Build Agents



Agents number

Specify how many agents you want to start. Every agent will be launched on a separate machine. If 0 is specified, no agent will start.

EC2 instance Type

Specify the type of instance for the TeamCity agents

Container CPU

Container CPU in virtual CPU units

Container Memory

Set to 2048 MiB by default.

3. Click Next. (Optional) In the dialog that appears, provide additional options if required.

4. Click Next, review your settings, accept the creation of AWS roles.

5. Click Сreate. No other actions are required. It takes about 15 minutes for the template to deploy the whole stack. Once the deployment is ready, you will see the TeamCity server endpoint in the Output section which points you to your TeamCity installation.

6. Access the TeamCity instance from your browser, create the administrators account and start using your TeamCity.

Connecting to server and viewing logs

To connect to the servers console, you need to use your instance private key:

ssh -i <path to private key\privatekey.pem> ec2-user@<server_IP_address>

To see teamcity-agent.log or teamcity-server.log, just run the docker logs command for the desired container. For example, for the server logs, run:

docker logs teamcity-server

Next Steps

Once you have TeamCity up and running, consider the following steps:

Upgrading TeamCity in AWS

To update TeamCity started from the CloudFormation template:

  1. In the AWS CloudFormation console, from the list of stacks, select the running TeamCity stack and use the Update Stack option.

  2. You will be redirected to the Select Template page: use the Current Template option and click Next.

  3. On the template settings page, enter the TeamCity version you want to update to. Note that if you previously used the TeamCity version tagged latest, you will now need to provide the actual version number as the latest tag can be applied to the server only once.

  4. Click Next, provide additional options if required, review the new settings and click Update. Once the Update is complete, access the TeamCity web UI from the browser.

  5. If required, provide the Super User token: to obtain it, you need to connect to your server instance, get the TeamCity server log as described above, and retrieve the maintenance token.

  6. Wait for the server to upgrade, log in to the TeamCity server and wait for the agent to upgrade and connect to the server.

Last modified: 11 January 2021