CircleCI Enterprise Installation Overview
This article provides a platform-independant overview of CircleCI Enterprise. CircleCI Enterprise matches the experience of https://circleci.com but runs behind your organization’s firewall, allowing your code, builds, and production hosts to be inaccessible outside of your network.
We are constantly working on making the installation process as smooth as possible and expanding the administrative tooling. We appreciate your feedback on ways to make CircleCI Enterprise easier and more valuable for you and your team, so please contact us at email@example.com with any suggestions.
To setup CircleCI, please have the following handy:
Domain name and associated DNS Records: GitHub requires applications to register their domains and authentication paths. For the purposes of this document, we will use
GitHub application client id/secret info: CircleCI must be registered with GitHub as an app. You can create a new app by visiting http://github-enterprise.example.com/applications/new to create an app that you own, or
http://github-enterprise.example.com/organizations/exampple-org/settings/applications/new to create an app owned by an organization (in this case
The authorization callback should use the url set earlier followed with
- SSL Key and Certificate for the domain: To secure the domain and enable GitHub enterprise webhooks, the service must be secured with SSL. The server requires an appropriate SSL private key and chained certificate files.
Once you have all of the prerequisites in place, you can either follow the detailed installation steps for AWS, or for non-AWS environments running Ubuntu. For other environments, contact us at firstname.lastname@example.org for a guided installation.
At a high level, CircleCI Enteprise has two kinds of instances that it needs in order to run: the services box and builder boxes.
The Services Box
The first is a services box which contains the CircleCI frontend and all internal resources we use to store data and run the service. This machine should not be restarted, and should be backed up regularly using our backup and restore process. You should have DNS resolution point to this machine’s IP.
|End Users||80, 443||HTTP/HTTPS Traffic|
|Builder Boxes||all traffic / all ports||Internal Communication|
|Github (Enterprise or .com)||80, 443||Incoming Webhooks|
The Builder Boxes
Our Builder Boxes handle running your builds, and store no state themselves. Each builder machine reserves 2CPU/4G for coordinating builds, and then uses the remaining space to create build containers. The larger machine, the more containers it will run. See our configuration doc for more information about how many containers a particular machine can run. Since they store no state, they can be scaled up or down at will. When shutting machines down, be sure to use the
circle-shutdown command to a gracefully shut down the machine.
|End Users||64535-65535||SSH into builds feature|
|Administrators||80, 443||CircleCI API Access (graceful shutdown, etc)|
|Services Box||all traffic / all ports||Internal Communication|
|Builder Boxes (including itself)||all traffic / all ports||Internal Communication|
|Services Box||22||Git Access|
|Services Box||80, 443||API Access|
|Builder Boxes||22||Git Access|
|Builder Boxes||80, 443||API Access|