Docs
circleci.com
Start Building for Free

Phase 2 - Core services

5 days ago8 min read
Server v4.x
Server Admin
On This Page

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

1. Create a namespace

Create a namespace to install the application into.

kubectl create ns <namespace>

2. Pull images

Credentials to pull the images from CircleCI’s image registry will be provided to you as part of the onboarding process. A docker-registry Kubernetes Secret will be used to pull images from Azure Container Registry (ACR). You have two options, depending on whether your application has access to the public internet.

3. Create helm values

Before installing CircleCI, it is recommended to create a new values.yaml file unique to your installation. The Installation Reference section contains some example values.yaml files that are a good place to start. The following describes the minimum required values to include in values.yaml. Additional customizations are available, see the provided values.yaml for all available options.

For sensitive data there are two options:

  • add into the values.yaml file

  • add them as Kubernetes Secrets directly

This flexibility allows you to manage Kubernetes Secrets using whichever process you prefer.

a. API token

The application requires a Kubernetes Secret containing an API token. This API token is used to facilitate internal API communication to api-service. Use a random string and store it securely, CircleCI will not be able to recover this value if lost. There are two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.

The application requires a session cookie key Kubernetes Secret, which CircleCI uses to sign session cookies. The Secret must be exactly 16 characters long. Use a random string and store it securely, CircleCI will not be able to recover this value if lost. There are two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.

c. Encryption

The application requires a Kubernetes Secret containing signing and encrpytion keysets. These keysets are used to encrypt and sign artifacts generated by CircleCI. These keys were created during the prerequisites phase. CircleCI will not be able to recover the values if lost. Depending on how you prefer to manage Kubernetes Secrets, there are two options.

d. Postgres credentials

The application requires a Kubernetes Secret containing Postgres credentials. This is true when using either the internal (default) or an externally hosted instance of Postgres. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are two options.

e. MongoDB credentials

The application requires a Kubernetes Secret containing MongoDB credentials. This is true when using either the internal (default) or an externally hosted instance of MongoDB. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are two options.

f. RabbitMQ configurations and auth Secrets

The RabbitMQ installation requires two random alphanumeric strings. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are two options.

g. Pusher Kubernetes Secret

The application requires a Kubernetes Secret for Pusher. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are 2 options:

h. Global

All values in this section are children of global in your values.yaml.

CircleCI domain name (required)

Enter the domain name you specified when creating your Frontend TLS key and certificate.

global:
  ...
  domainName: <domain-name-for-circleci>

License

A license has been provided by CircleCI, add it to values.yaml:

global:
  ...
  license: <license>

Registry

The registry to pull images from will have been provided to you, or you may have added the images to your own hosted registry. You will need to add the registry to values.yaml:

global:
  ...
  container:
    registry: <registry-domain eg: cciserver.azurecr.io >
    org: <your-org-if-applicable>

i. TLS

For TLS, you have 4 options:

j. GitHub integration

To configure GitHub with CircleCI, there are two options for providing credentials to the deployment. Steps for both GitHub and GitHub Enterprise (GHE) are given in the next two sections.

GitHub

These instructions are for the GitHub.com, not GitHub Enterprise. Use the client ID and secret you created with your Github OAuth application in the prerequisites phase.

GitHub Enterprise

The instructions for GitHub Enterprise are similar, with a few extra steps to enable Enterprise and create the required default token.

In the case of GitHub Enterprise add the defaultToken created in the prerequisite phase to the GitHub section. The hostname should not include the protocol, ex: github.exampleorg.com.

k. Object storage

Regardless of your storage provider, the bucket name you created during the prerequisites phase will need to be included.

object_storage:
  bucketName: <bucket-name>

S3 compatible

Add an s3 section as a child of object_storage. The endpoint in the case of AWS S3 is the regional endpoint, it is of the form https://s3.<region>.amazonaws.com. Otherwise it is the API endpoint fo your object storage server.

object_storage:
  ...
  s3:
    enabled: true
    endpoint: <storage-server-or-s3-endpoint>

Under object_storage.s3, you may provide the accessKey and secretKey, the irsaRole, or nothing. They were created during the prerequisites steps.

CircleCI server will use the role provided to authenticate to S3.

Google Cloud Storage

Under object_storage add the following.

gcs:
    enabled: true

Under object_storage.gcs you may add service_account, workloadIdentity, or neither. The keys/role were created during the prerequisites steps.

l. Installing behind a proxy

Depending on your security requirements, you might want to install CircleCI server behind a proxy. Installing behind a proxy gives you the power to monitor and control access between your installation and the broader Internet. For further information including limitations of installation behind a proxy, see the Installing Server Behind a Proxy guide.

The following fields need to be configured in your values.yaml:

  • Toggle proxy.enabled to "1"

  • Enter details for proxy.http.host and proxy.https.host, along with their associated ports. These values can be the same but they both need to be configured.

  • For authentication you will need to configure proxy.http.auth.enabled and proxy.https.auth.enabled as "1". You will also need to configure the respective username and password for both HTTP and HTTPS.

  • configure the no_proxy hosts and subnets. This should include localhost, your GitHub Enterprise host (optional), the hostname of your CircleCI installation (see Known Limitations for an explanation), and the CIDRs of both vm-service and Nomad.

proxy:
  enabled: "1"
  http:
    host: proxy.example.internal
    port: "3128"
    auth:
      enabled: "1"
      username: <proxy-user>
      password: <proxy-password>
  https:
    host: proxy.example.internal
    port: "3128"
    auth:
      enabled: "1"
      username: <proxy-user>
      password: <proxy-password>
  no_proxy:
    - localhost
    - 127.0.0.1
    - github.example.internal
    - circleci.example.internal
    - <nomad-subnet-cidr>
    - <vm-service-cidr>
    - <vpc-or-subnet-cidr>   # VPC or subnets to exclude from the proxy (optional)

4. Deploy

Once you have completed the fields detailed above, you can deploy CircleCI’s core services:

USERNAME=<provided-username>
PASSWORD=<token>
namespace=<your-namespace>
helm registry login cciserver.azurecr.io/circleci-server -u $USERNAME -p $PASSWORD
helm install circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version 4.0.0 -f <path-to-values.yaml>

5. Create DNS entry

Create a DNS entry for your NGINX load balancer, for example, circleci.your.domain.com and app.circleci.your.domain.com. 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 need the IP address, or, if using AWS, the DNS name of the NGINX load balancer. You can find this information with the following command:

kubectl get service circleci-proxy

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

6. Validation

You should now be able to navigate to your CircleCI server installation and log in to the application successfully.

Now we will 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 show a 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.

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.