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.

  1. Find the Amazon Machine Image for your region from the following list:
    Go!
  2. Ensure you choose an instance type with at least 16G of RAM.
  3. During the Configure Security Group step, open port 22 for SSH, 80 for HTTP, 443 for HTTPS, and 8800 for Custom TCP.
  4. (Optional) To enable developers to SSH into builds for debugging purposes, open ports 64535-65535 for Custom TCP.
  5. 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.
  6. Choose an SSL certificate option. By default, all machines in a CircleCI installation verify SSL certificates for the GitHub Enterprise instance. If you're 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](/docs/enterprise/docker-builder-config/) for details on setting builder machine environment variables.
  7. Upload the license file and set the admin password.
  8. 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 4 for the Homepage URL and using http(s)://AWS instance IP address/auth/github as the Authorization callback URL. Click the Register Application button.
  9. Copy the Client ID from GitHub and paste it into the entry field for GitHub Application Client ID.
  10. Copy the Secret from GitHub and paste it into the entry field for GitHub Application Client Secret and click Test Authentication.
  11. Create an s3 bucket for use by CircleCI, and input it in the "Storage" section. Ensure that the IAM User input or Instance Profile associated with the EC2 instance have full access to the bucket.
  12. 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.
  13. 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.
  14. 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.