Menu

CircleCI Trial Installation

CircleCI is a scalable CI/CD platform that supports clusters of tens or hundreds of build machines. This document provides instructions for installing and running the platform on a single virtual machine to provide a simple mechanism for getting started with a small trial in any environment:

Prerequisites

The following requirements must be met for successful trial installation:

  • Sign-up to receive a trial license file.
  • Use GitHub.com or GitHub Enterprise for version control.
  • Machines running CircleCI and GitHub must be able to reach each other on the network.
  • CircleCI machine must have outbound internet access. If you use a proxy server, contact us for instructions.

Steps for Installation on AWS EC2

Use this procedure to install CircleCI on a single EC2 VM by using the pre-made Amazon Machine Image (AMI) which is a special type of virtual appliance that is used to create a virtual machine within the Amazon Elastic Compute Cloud (“EC2”).

Note: All builds that run on the installed machine will have access to the AWS Identity and Access Management (IAM) privileges associated with its instance profile. Do not give any inappropriate privileges to your instance. It is possible to block this access with iptables rules in a production setup, contact support for specific instructions.

Configure the Amazon Machine Image:

Go!

  1. Find the Amazon Machine Image for your region from the list above.
  2. Ensure you choose an instance type with at least 16G of RAM, such as t2.xlarge. Select Next to configure the instance.
  3. On the Configuring Instance Details page:
    • Choose your network
    • Enable Auto-assign Public IP
    • Set the IAM role to None AWS Step 3
  4. By default, the instance will have 100GB of storage, this is enough for the trial install.
  5. During the Configure Security Group step, open the following ports:
    • SSH port 22
    • HTTP port 80
    • HTTPS port 443
    • Custom TCP 8800
    • (Optional) To enable developers to SSH into builds for debugging purposes, open ports 64535-65535 for Custom TCP. AWS Step 5
  6. After the VM is lauched, go to the public or private IP address or hostname for the VM and click Get Started to complete the rest of the guided installation process for CircleCI.

Configure CircleCI

  1. Choose an SSL certificate option. By default, all machines in a CircleCI installation verify SSL certificates for the GitHub Enterprise instance.
    • Note: If you are using a self-signed cert, or using a custom CA root, select the HTTPS (with self-signed certificate) option in the System Console at port 8800. You also need to export CIRCLE_IGNORE_CERT_HOST=insecure-ghe.example.com on builder machines replacing insecure-ghe.example.com with the host of your GitHub Enterprise instance. See this doc for details on setting builder machine environment variables.
  2. Upload the CircleCI license file and set the admin password.
  3. If you do not need 1.0 build functionality, leave the box for it unchecked. Most users should check the box for 2.0 functionality.
  4. Select “Single Box” in the “Builders Configuration” section(s).
  5. Register CircleCI as a new OAuth application in GitHub.com at https://github.com/settings/applications/new/ or in the GitHub Enterprise Settings using the IP address of the AWS instance from Step 6 for the Homepage URL and using http(s)://AWS instance IP address/auth/github as the Authorization callback URL. Click the Register Application button.
  6. Copy the Client ID from GitHub and paste it into the entry field for GitHub Application Client ID.
  7. Copy the Secret from GitHub and paste it into the entry field for GitHub Application Client Secret and click Test Authentication.
  8. Ensure that “None” is selected in the “Storage” section. In production installations, other object stores may be used but will require corresponding IAM permissions.
  9. Ensure that the “VM Provider” is set to “None”. If you would like to allow CircleCI to dynamically provision VMs (e.g. to support doing Docker builds) you may change this setting, but it will require additional IAM permissions. Contact us if you have questions.
  10. Agree to the license agreement and save. The application start up process begins by downloading the ~160 MB Docker image, so it may take some time to complete.
  11. Open the CircleCI app and click Get Started to authorize your GitHub account. The Add Projects page appears where you can select a project for your first build.