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 CircleCI platform on a single virtual machine. This is intended as a simple mechanism for getting started with a small trial in any environment:
- Steps for Installation on AWS EC2
The following requirements must be met for a successful trial installation:
- Sign-up to receive a CircleCI trial license file.
- You will need an AWS account.
- 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 machines must have outbound internet access. If you use a proxy server, contact us for instructions.
Steps for Installation on AWS EC2
The steps in this section walk you through installing CircleCI on a single EC2 VM using a pre-made Amazon Machine Image (AMI). An AMI is a special type of virtual appliance 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:
- Find the Amazon Machine Image for your region from the list above, and click Go!
- Ensure you choose an instance type with at least 32G of RAM, such as
m4.2xlarge, from the list. Select Next: Configure Instance Details.
- On the Configuring Instance Details page:
- Choose your network
- Enable Auto-assign Public IP
- Check the IAM role is set to None
- Then select Next: Add Storage.
- By default, the instance will have 100GiB of storage, this is enough for the trial install. Select Next: Add Tags.
- You don’t need to add a tag for the purposes of this trial but feel free to do so using the Add Tag button. Select Next: Configure Security Group.
- On the Configure Security Group page, 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.
- Then select Review and Launch to see a summary of your trial instance, then select Launch.
- You should now be looking at the Launch Status Page. From here you can select View Instances to jump to your AWS dashboard and see the full details of your trial instance. Once the instance is up and running, go to the public or private IP address or hostname and click Get Started to complete the rest of the guided installation process for CircleCI. Note: your browser may warn you that the Get Started link is unsafe.
- Choose an SSL certificate option and enter a hostname if relevant. This is where you can upload the licence file you were provided with when you signed up for your CircleCI account. Otherwise, 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, please see the certificates document for a script to add the information to the CircleCI truststore.
- Once you have uploaded your CircleCI licence file you can decide how to secure your admin console. You have three options:
- Anonymous admin access to the console, anyone on port8800 can access. (not-recommended).
- Set a password that can be used to securely access the admin console (recommended).
- Use your existing directory-based authentication system (LDPA).
- Your CircleCI instance will now be put through a set of preflight checks, once they have completed, click Continue.
- On the Settings page, address the following:
- Enter your hostname, or IP address if you didn’t set one, and click Test Hostname Resolution.
- Under Execution Engines, 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.
- Under 2.0 Builders Configuration, select “Single Box”.
- Follow the GitHub integration instructions. Note: If you get an “Unknown error authenticating via GitHub. Try again, or contact us.” message, try using
https:for the Homepage URL and callback URL.
- Ensure that “None” is selected in the “Storage” section. In production installations, other object stores may be used but will require corresponding IAM permissions.
- 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.
- Agree to the license agreement, save and head to your Dashboard. The application start up process begins by downloading the ~160 MB Docker image, so it may take some time to complete.
- Click Open to launch the CircleCI app and click Sign Up to authorize your GitHub account. The Add Projects page appears where you can select a project for your first build.