CircleCI Server v3.x Configuring External Services

Last updated
Tags Server v3.x Server Admin

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. Get to the KOTS admin console by running the following, substituting your namespace: kubectl kots admin-console -n <YOUR_CIRCLECI_NAMESPACE>

  • PostgreSQL

  • MongoDB

  • Vault

PostgreSQL

If using your own PostgresSQL instance it needs to be version 12.1 or greater.
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 used to access your PostgreSQL instance.

Best Practices for your PostgreSQL

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

# of Daily Active Users # of PostgreSQL Replicas CPU RAM Disk NIC 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 backup

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

  • Performing a backup before each upgrade of CircleCI server.

MongoDB

If using your own MongoDB instance it needs to be version 3.6 or greater.
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 need to 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.