Start Building for Free

Customization and Configuration

1 week ago3 min read
Server v2.x
Server Admin
On This Page

The following sections summarize the key files and variables that impact CircleCI server behavior, and configuration options for your server installation.

Notable Files & Folders

NeedPathMore info

General Config


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


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

PropertyImpactMore info


Override the scheme and host that CircleCI uses


Set JVM heap size for all containers reading this property

Use container specific settings when possible (see files above)

Other Properties and Env Vars

PropertyImpactMore info


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.

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


Resource 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.

Following are the steps required to customize resource classes for the Docker 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.

  5. Run:

    echo 'export CIRCLE_DISPATCHER_RESOURCE_DEF=/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

  ;; 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.
  {: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 keyword medium 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.

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

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 (

Example of banner
Figure 1. Login Screen Banner Example

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.

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.