CircleCI Server v3.x Installation Phase 2

Last updated
Tags Server v3.x Server Admin

Before you begin with the CircleCI server v3.x core services installation phase, ensure all prerequisites are met.

In the following sections replace any items or credentials displayed between < > with your details.
Flow chart showing the installation flow for server 3.x with phase 2 highlighted
Figure 1. Installation Experience Flow Chart Phase 2

Phase 2: Core services installation

CircleCI server v3.x uses KOTS from Replicated to manage and distribute server v3.x. KOTS is a kubectl plugin. To install the latest version, you can run curl | bash.

Ensure you are running the minimum KOTS version (1.47.3) by running:

kubectl kots version
The KOTS command will open up a tunnel to the admin console. If running on Windows inside WSL2, the port is not available on the host machine. Turning WSL off and back on should resolve the issue. For more information, please see

From the terminal run (if you are installing behind a proxy see Installing behind HTTP Proxy):

kubectl kots install circleci-server

You will be prompted for a:

  • namespace for the deployment

  • password for the KOTS admin console

When complete, you should be provided with a URL to access the KOTS admin console, usually, http://localhost:8800.

If you need to get back to the KOTS admin console at a later date you can run: kubectl kots admin-console -n <YOUR_CIRCLECI_NAMESPACE>
Once you have created your namespace we recommend setting your kubectl context too with the following command: kubectl config set-context --current --namespace <namespace>

Installing behind HTTP Proxy

If you wish to install CircleCI server behind a proxy, the following command structure should be used (for more information see the KOTS docs here):

kubectl kots install circleci-server --http-proxy <YOUR_HTTP_PROXY_URI> --https-proxy <https-proxy> --no-proxy <YOUR_NO_PROXY_LIST>

The load balancer endpoints must be added to the no-proxy list for the following services: output processor and vm-service. This is because the no-proxy list is shared between the application and build-agent. The application and build-agent are assumed to be behind the same firewall and therefore cannot have a proxy between them.

For further information see the Configuring a Proxy guide.

Frontend Settings

Frontend settings control the web application specific aspects of the CircleCI system.

Screenshot showing frontend settings
Figure 2. Frontend Settings

Complete the fields described below. You can either supply a private key and certificate or check the box to allow Let’s Encrypt to automatically request and manage certificates for you. You can also disable TLS termination at this point, but the system will still need to be accessed over HTTPS.

If you are selecting the option to use private load balancers, the Let’s Encrypt option will no longer work and become unavailable.
  • Domain Name (required) - Enter the domain name you specified when creating your Frontend TLS key and certificate.

  • Frontend Replicas (optional) - Used to increase the amount of traffic that can be handled by the frontend.

  • Frontend TLS Private Key (required) - You created this during your pre-requisite steps. You can retrieve this value with the following command: `

    cat /etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN>/privkey.pem
  • Frontend TLS Certificate (required) - You created this during your pre-requisite steps. You can retrieve this value with the following command:

    cat /etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN>/fullchain.pem
  • Private Load Balancer (optional) - Load balancer doesn’t generate external IP addresses.

Artifact and Encryption Signing Settings

Encryption and artifact signing keys were created during prerequisites phase. You can enter them here now.

Complete the following fields:

  • Artifact Signing Key (required)

  • Encryption Signing Key (required)

Github Settings

You created your Github OAuth application in the prerequisite phase, use the data to complete the following:

  • Github Type (required) - Select Cloud or Enterprise (on premises).

  • OAuth Client ID (required) - The OAuth Client ID provided by Github.

  • OAuth Client Secret (required) - The OAuth Client Secret provided by Github.

Object Storage Settings

You created your Object Storage Bucket and Keys in the prerequisite steps, use the data to complete the following:

S3 Compatible

You should have created your S3 Compatible bucket and optional IAM account during the prerequisite steps.

  • Storage Bucket Name (required) - The bucket used for server.

  • Access Key ID (required) - Access Key ID for S3 bucket access.

  • Secret Key (required) - Secret Key for S3 bucket access.

  • AWS S3 Region (optional) - AWS region of bucket if your provider is AWS. S3 Endpoint is ignored if this option is set.

  • S3 Endpoint (optional) - API endpoint of S3 storage provider. Required if your provider is not AWS. AWS S3 Region is ignored if this option is set.

  • Storage Object Expiry (optional) - Number of days to retain your test results and artifacts. Set to 0 to disable and retain objects indefinitely.

Google Cloud Storage

You should have created your Google Cloud Storage bucket and service account during the prerequisite steps.

  • Storage Bucket Name (required) - The bucket used for server.

  • Service Account JSON (required) - A JSON format key of the Service Account to use for bucket access.

  • Storage Object Expiry (optional) - Number of days to retain your test results and artifacts. Set to 0 to disable and retain objects indefinitely.

Postgres, MongoDB, Vault settings

You can skip these sections unless you plan on using an existing Postgres, MongoDB or Vault instance, in which case see the Externalizing Services doc. By default CirecleCI server will create its own Postgres, MongoDB and Vault instances within the CircleCI namespace. The instances inside the CircleCI namespace will be included in the CircleCI backup and restore process.

Save and deploy

Once you have completed the fields detailed above it is time to deploy. The deployment will install the core services and provide you an IP address for the Traefik load balancer. That IP address will be critical in setting up a DNS record and completing the first phase of the installation.

In this first stage we skipped a lot of fields in the config. Not to worry. We will revisit those in the next stages of installation.

Create DNS entry

Create a DNS entry for your Traefik load balancer, for example, and The DNS entry should align with the DNS names used when creating your TLS certificate and GitHub OAuth app during the prerequisites steps. All traffic will be routed through this DNS record.

You will need the IP address or, if using AWS, the DNS name of the Traefik load balancer. You can find this with the following command:

kubectl get service circleci-server-traefik --namespace=<YOUR_CIRCLECI_NAMESPACE>

For more information on adding a new DNS record, see the following documentation:


You should now be able to navigate to your CircleCI server installation and log in to the application successfully. Now let’s move on to build services. It may take a while for all your services to be up. You can periodically check by running the following command (you are looking for the “frontend” pod to be status of running and ready should show 1/1):

kubectl get pods -n <YOUR_CIRCLECI_NAMESPACE>

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.