Search Results for ""

Customization and Configuration

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

/etc/circle-installation-customizations

See table below for values

JVM Heap Sizes

/etc/circleconfig/XXXX/customizations Supports: frontend, test_results

Adjust heap size for individual containers with JVM_HEAP_SIZE

Custom CA Certs

/usr/local/share/ca-certificates/

Container Customizations

/etc/circleconfig/XXX/customizations

Used lots of places in replicated

/etc/hosts

/etc/hosts

Respected by several containers including frontend, copied to container’s /etc/hosts

/etc/environment

/etc/environment

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/customizations

Resource Classes

Introduced in CircleCI Server v2.18

You can customize resource classes for your installation to provide developers with CPU/RAM options for the Jobs they configure.

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 and machine executors:

  1. SSH into the Services machine.

  2. Run the following:

    sudo mkdir /etc/circleconfig/picard-dispatcher
  3. Run the following:

    sudo vim /etc/circleconfig/picard-dispatcher/resource-definitions.edn
  4. Add your required customizations to the file, then save and exit vim with :wq - see below for options and formatting.

    It is important to use the IDs listed in the example below for both machine and Docker resources classes.
  5. Run:

    echo 'export CIRCLE_DISPATCHER_RESOURCE_DEF=/etc/circleconfig/picard-dispatcher/resource-definitions.edn' | sudo tee /etc/circleconfig/picard-dispatcher/customizations
  6. 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
  {:small {:id "d1.small" :ga true :ui {:cpu 2.0 :ram 4096 :class :small} :outer {:cpu 2.0 :ram 4096}}
   :medium {:id "d1.medium" :ga true :ui {:cpu 4.0 :ram 8192 :class :medium} :outer {:cpu 4.0 :ram 8192}}
   :massive {:id "d1.massive" :ga true :ui {:cpu 7.0 :ram 28000 :class :massive} :outer {:cpu 7.0 :ram 28000}}}

  :machine
  {:medium {:id "l1.medium" :ga true :ui {:cpu 2.0 :ram 7680 :class :medium} :outer {:cpu 2.0 :ram 256}}
   :large {:id "l1.large" :ga true :ui {:cpu 4.0 :ram 16000 :class :large} :outer {:cpu 2.0 :ram 256}}}}}

Let’s take a look at one of the options in more detail

:medium {:id "d1.medium" :ga true :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 is 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 but you will need to use the listed IDs for machine resources.

  • :ga true - 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.

Enable the Large Resource Class for Machine Executor

Introduced in CircleCI Server v2.18

To use second machine type (large in the example above), a further step is required to enable this for your organization. Following are the required steps:

  1. SSH into the Services .achine

  2. Run the following:

circleci dev-console
  1. Run the following (substituting your organization name):

(admin/set-org-feature-unsafe "<org_name>" :picard-allowed-resource-classes :val #{"l1.large"})
  1. Alternatively, if you only want to enable only a single project to use the large machine resource class you can run the following (substituting your project URL):

(admin/set-project-feature-by-url "<github_url_of_project>" :picard-allowed-resource-classes #{"l1.large"})

Login Screen

Introduced in CircleCI Server v2.17.3

You can add a banner to your login screen as follows:

  1. Access the file: /etc/circleconfig/frontend/customizations on the Services machine

  2. Add the following line, substituting the text you wish to display in the banner:

    export CIRCLE__OUTER__LOGIN_BANNER_MESSAGE="<insert-your-message-here>
  3. Restart CircleCI from the Management Console (your-circleci-hostname.com:8800)

banner
Figure 1. Login Screen Banner Example