Customization and Configuration
Server v2.x Server Admin | CircleCI Server version 2.x is no longer a supported release. Please consult your account team for help in upgrading to a supported release. |
The following sections summarize the key files and variables that impact CircleCI server behavior, and configuration options for your server installation.
Notable Files & Folders
| Need | Path | More info |
|---|---|---|
General Config |
| See table below for values |
JVM Heap Sizes |
| Adjust heap size for individual containers with |
Custom CA Certs |
| |
Container Customizations |
| Used in lots of places by CircleCI containers |
|
| Respected by several containers including frontend, copied to container’s /etc/hosts |
|
| Respected by all containers |
Properties of /etc/circle-installation-customizations
Every property should be in the format export ENV_VAR="value" |
| Property | Impact | More info |
|---|---|---|
CIRCLE_URL | Override the scheme and host that CircleCI uses | |
JVM_HEAP_SIZE | Set JVM heap size for all containers reading this property | Use container specific settings when possible (see files above) |
Other Properties and Env Vars
| Property | Impact | More info |
|---|---|---|
HTTP_PROXY, NO_PROXY | Proxy for replicated and other services outside CircleCI containers to use |
Service Configuration Overrides
This section describes the configuration interface for overriding services in CircleCI server.
| Customizing your configuration can have potentially damaging consequences, so we recommend contacting support@circleci.com for guidance before making any changes. |
Configuration is done by exporting environment variables in files located on the Services machine.
Consider the file “customizations” created at the following path /etc/circleconfig/workflows-conductor:
export FOO="bar"The value of FOO will take precedence over the default values set in the default container mapping in the CircleCI server configuration.
Available Overrides
/etc/circleconfig/api-service/customizations
/etc/circleconfig/audit-log-service/customizations
/etc/circleconfig/contexts-service-db-migrator/customizations
/etc/circleconfig/contexts-service/customizations
/etc/circleconfig/cron-service-db-migrator/customizations
/etc/circleconfig/cron-service/customizations
/etc/circleconfig/domain-service-migrator/customizations
/etc/circleconfig/domain-service/customizations
/etc/circleconfig/federations-service-db-migrator/customizations
/etc/circleconfig/federations-service-migrator/customizations
/etc/circleconfig/frontend/customizations
/etc/circleconfig/output-processor/customizations
/etc/circleconfig/permissions-service-migrator/customizations
/etc/circleconfig/permissions-service/customizations
/etc/circleconfig/picard-dispatcher/customizations
/etc/circleconfig/schedulerer/customizations
/etc/circleconfig/test-results/customizations
/etc/circleconfig/vm-gc/customizations
/etc/circleconfig/vm-scaler/customizations
/etc/circleconfig/vm-service-db-migrator/customizations
/etc/circleconfig/vm-service/customizations
/etc/circleconfig/workflows-conductor/customizationsResource Classes
Introduced in CircleCI server v2.19
You can customize resource classes for your installation to provide developers with CPU/RAM options for the Jobs they configure.
The resources for machine executors can’t be configured using the method described on this page. To change CPU and memory size for VMs, change AWS Instance Type in the VM Provider section of the Management Console. See the VM Service guide for more details. |
| Once resource classes are set using the steps below, make these options available to developers so they can ensure correct usage. |
Following are the steps required to customize resource classes for the Docker executors:
-
SSH into the Services machine.
-
Run the following:
sudo mkdir /etc/circleconfig/picard-dispatcher -
Run the following:
sudo vim /etc/circleconfig/picard-dispatcher/resource-definitions.ednThis file replaces the full resource class definition for your installation so it is important to include all resource classes your users need at this point, not just those you wish to customize. -
Add your required customizations to the file, then save and exit vim with
:wq- see below for options and formatting. -
Run:
echo 'export CIRCLE_DISPATCHER_RESOURCE_DEF=/circleconfig/picard-dispatcher/resource-definitions.edn' | sudo tee /etc/circleconfig/picard-dispatcher/customizations -
Restart the CircleCI server application. The application can be stopped and started again from the Management Console Dashboard (for example,
<circleci-hostname>.com:8800).
Below is an example resource class configuration:
Example config:
{:default-resource-class :medium
:resource-classes
{:docker
;; Modify below
{:small {:id "d1.small" :availability :general :ui {:cpu 2.0 :ram 4096 :class :small} :outer {:cpu 2.0 :ram 4096}}
:medium {:id "d1.medium" :availability :general :ui {:cpu 4.0 :ram 8192 :class :medium} :outer {:cpu 4.0 :ram 8192}}
:massive {:id "d1.massive" :availability :general :ui {:cpu 7.0 :ram 28000 :class :massive} :outer {:cpu 7.0 :ram 28000}}}
;; Modify above
;; NOTE: Do not delete or modify the following block: Such attempts will break machine builds.
:machine
{:medium {:id "l1.medium" :availability :general :ui {:cpu 2.0 :ram 4096 :class :medium} :outer {:cpu 1 :ram 512}}
:large {:id "l1.large" :availability :general :ui {:cpu 4.0 :ram 16384 :class :medium} :outer {:cpu 1 :ram 512}}
:windows.medium {:id "windows.medium" :availability :general :ui {:cpu 2.0 :ram 8192 :class :windows.medium} :outer {:cpu 1 :ram 512}}}}}Let’s take a look at one of the options in more detail
:medium {:id "d1.medium" :availability :general :ui {:cpu 4.0 :ram 8192 :class :medium} :outer {:cpu 4.0 :ram 8192}-
:medium- this is the name that your developers will use to refer to the resource class in their config.yml and the keywordmediumis the external facing name of the resource class. -
:id "d1.medium"- this is the internal name for the resource class. You can customize this ID for Docker resource classes. -
:availability :general- required field -
:ui {:cpu 4.0 :ram 8192 :class :medium}- Information used by the CircleCI UI. This this should be kept in parity with :outer - see below. -
:outer {:cpu 4.0 :ram 8192}- This defines the CPU and RAM for the resource class.
| Jobs can only run if the Nomad client has enough CPU/RAM in order to allocate the resources required. If not, the job will be queued. See our Nomad metrics guide for information on monitoring the capacity of your Nomad cluster, and Nomad Client System Requirements for more about capacity, and how Nomad allocates jobs. |
Login Screen
Introduced in CircleCI Server v2.17.3
You can add a banner to your login screen as follows:
-
Access the file:
/etc/circleconfig/frontend/customizationson the Services machine -
Add the following line, substituting the text you wish to display in the banner:
export CIRCLE__OUTER__LOGIN_BANNER_MESSAGE="<insert-your-message-here>" -
Restart CircleCI from the Management Console (your-circleci-hostname.com:8800)
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
