Start Building for Free

Installation Prerequisites

5 days ago2 min read
Server v2.x
On This Page
  • Private Subnet Requirements
  • Planning

CircleCI uses Terraform to automate parts of the infrastructure for your CircleCI server v2.x install, so you will need to install this first:

Ensure you have the following information available before beginning the installation procedure:

  • A CircleCI License file (.rli). Contact CircleCI support for a license and request a cluster-enabled license to run jobs on dedicated instances for best performance.

  • Your AWS Access Key ID and Secret Access Key.

  • Name of your AWS EC2 key pair.

  • AWS Region, for example us-west-2.

  • AWS Virtual Private Cloud (VPC) ID and AWS Subnet ID. If your account is configured to use a default VPC, your default VPC ID is listed under Account Attributes, which you will find from the AWS management console on the EC2 dashboard page.

  • Set your VPC (enableDnsSupport) setting to true to ensure that queries to the Amazon provided DNS server at the IP address, or the reserved IP address at the base of the VPC IPv4 network range plus two will succeed. See the Using DNS with Your VPC Amazon Web Services documentation for additional details.

Private Subnet Requirements

The following additional settings are required to support using private subnets on AWS with CircleCI:

  • The private subnet for builder boxes must be configured with a NAT gateway or an internet gateway configured for the outbound traffic to the internet via attached route tables.

  • The VPC Endpoint for S3 should be enabled. Enabling the VPC endpoint for S3 should significantly improve S3 operations for CircleCI and other nodes within your subnet.

  • Adequately power the NAT instance for heavy network operations. Depending on the specifics of your deployment, it is possible for NAT instances to become constrained by highly parallel builds using Docker and external network resources. A NAT that is inadequate could cause slowness in network and cache operations.

  • If you are integrating with, ensure that your network access control list (ACL) allows ports 80 and 443 for GitHub webhooks. When integrating with GitHub, either set up CircleCI in a public subnet, or set up a public load balancer to forward traffic.

  • See the Services Machine section of our overview for more information on the specific ports that need to be accessible to instances in your CircleCI installation.


Have available the following information and policies before starting the installation:

  • If you use network proxies, contact your Account team before beginning your install.

  • Plan to provision at least two AWS instances, one for Services and one for your first set of Nomad Clients. Best practice is to use an m4.2xlarge instance with 8 vCPUs and 32GB RAM for both the Services and Nomad Clients instances.

  • AWS instances must have outbound access to pull Docker containers and to verify your license. If you don’t want to give open outbound access, see our list of ports that will need access.

  • In order to provision required AWS entities with Terraform you will require an IAM User with the following permissions (See the AWS guidance on creating IAM users):

        "Version": "2012-10-17",
        "Statement": [
                "Action": [
                "Effect": "Allow",
                "Resource": [
                "Action": [
                "Resource": [
                "Effect": "Allow"

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.