Docs
circleci.com
Start Building for Free

CircleCI Server v3.x Configuring External Services

2 months ago2 min read
Server v3.x
Server Admin
On This Page

This document describes how to configure the following external services for use with a CircleCI server 3.x installation. The settings described in this guide can be found in the KOTS Admin Console. Access the KOTS Admin Console by running the following command, substituting your namespace: kubectl kots admin-console -n <YOUR_CIRCLECI_NAMESPACE>

PostgreSQL

Screenshot of KOTS admin console config showing settings for using an external PostgreSQL instance
Figure 1. External PostgreSQL

If you choose to use an external PostgreSQL instance, complete the following fields:

  • PostgreSQL Service Domain (required) - The domain or IP address of your PostgreSQL instance.

  • PostgreSQL Service Port (required) - The port of your PostgreSQL instance.

  • PostgreSQL Service Username (required) - A user with the appropriate privileges to access your PostgreSQL instance.

  • PostgreSQL Service Password (required) - The password of the user account used to access your PostgreSQL instance.

Best Practices for your PostgreSQL

Consider running at least two PostgreSQL replicas to allow recovery from primary failure and for backups. The table below shows the recommended specifications for PostgreSQL machines:

# of Daily Active Users# of PostgreSQL ReplicasCPURAMDiskNIC Speed

<50

2

8 Cores

16 GB

100 GB

1 Gbps

50 - 250

2

8 Cores

16 GB

200 GB

1 Gbps

250 - 1000

3

8 Cores

32 GB

500 GB

10 Gbps

1000 - 5000

3

8 Cores

32 GB

1 TB

10 Gbps

5000+

3

8 Cores

32 GB

1 TB

10 Gbps

Backing Up PostgreSQL

PostgreSQL provides official documentation for backing up and restoring your PostgreSQL 12 install, which can be found here.

We strongly recommend the following:

  • Taking daily backups.

  • Keeping at least 30 days of backups.

  • Using encrypted storage for backups as databases might contain sensitive information.

  • Performing a backup before each upgrade of CircleCI server.

MongoDB

Screenshot of KOTS admin console config showing settings for using an external MongoDB instance
Figure 2. External MongoDB

If you choose to use an external MongoDB instance, complete the following fields:

  • MongoDB connection host(s) or IP(s) (required) - The hostname or IP of your MongoDB instance. Specifying a port using a colon and multiple hosts for sharded instances are both supported.

  • Use SSL for connection to MongoDB (required) - Whether to use SSL when connecting to your external MongoDB instance.

  • Allow insecure TLS connections (required) - If you use a self-signed certificate or one signed by a custom CA, you will need to enable this setting. However, this is an insecure setting and you should use a TLS certificate signed by a valid CA, if you can.

  • MongoDB user (required) - The username for the account to use. This account should have the dbAdmin role.

  • MongoDB password (required) - The password for the account to use.

  • MongoDB authentication source database (required) - The database that holds the account information, usually admin.

  • MongoDB authentication mechanism (required) - The authentication mechanism to use, usually SCRAM-SHA-1.

  • Additional connection options (optional) - Any other connection options you would like to use. This needs to be formatted as a query string (key=value pairs, separated by &. Special characters must be URL encoded). See the MongoDB docs for available options.

Vault

Screenshot of KOTS Admin Console config showing settings for using an external Vault instance
Figure 3. External Vault

If you choose to use an external Vault instance, complete the following fields:

  • URL - The URL to your Vault service.

  • Transit Path - Your Vault secrets transit path.

  • Token - The access token for vault.


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.