Skip to content
Docs
Cancel

Setting Up HTTP Proxies

Last updated
Tags Server v2.x Server Admin
CircleCI Server version 2.x is no longer a supported release. Please consult your account team for help in upgrading to a supported release.

This section describes how to configure CircleCI to use an HTTP proxy.

Overview

If you are setting up your proxy through Amazon, read this before proceeding:

Using an HTTP Proxy - AWS Command Line Interface

Avoid proxying internal requests, especially for the Services machine. To add these to the NO_PROXY rules, run:

export NO_PROXY=<services_box_ip>

In an ideal case, traffic to S3 will not be proxied, and will instead be bypassed by adding s3.amazonaws.com,*.s3.amazonaws.com to the NO_PROXY rule.

These instructions assume an unauthenticated HTTP proxy at 10.0.0.33:3128, a Services machine at 10.0.1.238 and use of ghe.example.com as the GitHub Enterprise host.

The following proxy instructions must be completed before installing CircleCI on fresh VMs or instances. You must also configure JVM OPTs again as described below.

Service Machine Proxy Configuration

The Service machine has many components that need to make network calls, as follows:

  • External Network Calls - Replicated is a vendor service that we use for the Management Console of CircleCI. CircleCI requires Replicated to make an outside call to validate the license, check for updates, and download upgrades. Replicated also downloads docker, installs it on the local machine, and uses a Docker container to create and configure S3 buckets. GitHub Enterprise may or may not be behind the proxy, but github.com will need to go through the proxy.

  • Internal Network Calls

    • If S3 traffic requires going through an HTTP proxy, CircleCI must pass proxy settings into the container.

    • The CircleCI instance on the Services machine runs in a Docker container, so it must to pass the proxy settings to the container to maintain full functionality.

Set up Service Machine Proxy Support

For a static installation, not on AWS, SSH into the Services machine and run the following code snippet with your proxy address:

echo '{"HttpProxy": "http://<proxy-ip:port>"}' | sudo tee /etc/replicated.conf
(cat <<'EOF'
export HTTP_PROXY=<proxy-ip:port>
export HTTPS_PROXY=<proxy-ip:port>
EOF
) | sudo tee -a /etc/circle-installation-customizations

systemctl restart replicated\*

If you run in Amazon’s EC2 service then you’ll need to include 169.254.169.254 EC2 services as shown below:

echo '{"HttpProxy": "http://<proxy-ip:port>"}' | sudo tee /etc/replicated.conf
(cat <<EOF
export HTTP_PROXY=<proxy-ip:port>
export HTTPS_PROXY=<proxy-ip:port>
export NO_PROXY=169.254.169.254,<circleci-service-ip>,127.0.0.1,localhost,ghe.example.com
export JVM_OPTS="-Dhttp.proxyHost=<proxy-ip> -Dhttp.proxyPort=<proxy-port> -Dhttps.proxyHost=<proxy-ip> -Dhttps.proxyPort=<proxy-port> -Dhttp.nonProxyHosts=169.254.169.254|<circleci-service-ip>|127.0.0.1|localhost|ghe.example.com"
EOF
) | sudo tee -a /etc/circle-installation-customizations

systemctl restart replicated\*
NOTE: If the proxy requires user authentication, you will need to add user authentication information into <proxy-ip> like below: 
export HTTP_PROXY=http://<userid>:<password>@<proxy-ip>:<port>
export HTTPS_PROXY=https://<userid>:<password>@<proxy-ip>:<port>
The above is not handled by by our enterprise-setup script and will need to be added to the user data for the Services Machine startup or done manually.

Corporate Proxies

When our instructions ask if you use a proxy, you will also be prompted to input the address. It is very important that you input the proxy in the following format: <protocol>://<ip>:<port>. If you miss any part, then apt-get won’t work correctly and the packages won’t download.

Nomad Client Configuration

External Network Calls

CircleCI uses curl and awscli scripts to download initialization scripts, along with jars from Amazon S3. Both curl and awscli respect environment settings, but if you have allowed traffic from Amazon S3 you should not have any problems.

Internal Network Calls

  • CircleCI JVM:

    • Any connections to other Nomad Clients or the Services machine should be excluded from HTTP proxy

    • Connections to GitHub Enterprise should be excluded from HTTP proxy

  • The following contains parts that may be impacted due to a proxy configuration:

    • Amazon EC2 metadata. This should not be proxied. If it is, then the machine will be misconfigured.

    • Amazon S3 traffic — note S3 discussion above

    • Amazon EC2 API - EC2 API traffic may need to be proxied. You would note lots of failures (timeout failures) in logs if the proxy setting is misconfigured, but it will not block CircleCI from functioning.

Nomad Client Proxy Setup

  • If you are installing CircleCI server on AWS using Terraform, you should add the below to your Nomad client launch configuration – these instructions should be added to /etc/environment.

  • If you are using Docker refer to the Docker HTTP Proxy Instructions documentation.

  • If you are running a static installation, add the following to the server before installation:

    #!/bin/bash

(cat <<EOF
HTTP_PROXY=<proxy-ip:port>
HTTPS_PROXY=<proxy-ip:port>
NO_PROXY=169.254.169.254,<circleci-service-ip>,127.0.0.1,localhost,ghe.example.com
JVM_OPTS="-Dhttp.proxyHost=<ip> -Dhttp.proxyPort=<port> -Dhttps.proxyHost=<proxy-ip> -Dhttps.proxyPort=3128 -Dhttp.nonProxyHosts=169.254.169.254|<circleci-service-ip>|127.0.0.1|localhost|ghe.example.com"
EOF) | sudo tee -a /etc/environment

set -a
. /etc/environment

    If your containers need to use a proxy server you will need to set the following schedulerer environment variables: DOCKER_HTTP_PROXY, DOCKER_HTTPS_PROXY, NO_PROXY, corresponding to those listed in the Docker instructions. This will ensure your containers have outbound/proxy access. For more information on creating configuration overrides, see the Customizations Guide.

Troubleshooting

Can’t access the Management Console

If you cannot access the CircleCI Management Console, but the Services machine seems to be running, try to SSH tunnel into the machine by running the following, substituting your proxy address and the IP address of your Services machine:

ssh -L 8800:<address you want to proxy through>:8800 ubuntu@<ip_of_services_machine>

REPL time out

If you experience a timeout when connecting to the REPL, you will need to allow access, through your corporate proxy, to the domains of any Clojure library repositories that are required to download dependencies for running the REPL.

sudo su
docker exec -it frontend /bin/bash
lein repl :connect 6005

Refer to the error output for guidance on which repositories need to be granted access. The list will be different for each corporate proxy, but following is an example list:

  • repo1.maven.org

  • build.clojure.org

  • clojars.org

  • repo.clojars.org

Data Persistence

Contact CircleCI Support to discuss externalizing services for data persistence.


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.

Creative Commons License
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

6,000 Minutes Free

CircleCI, now with more build minutes
than anyone else for FREE 🎉

Sign up for Free

These teams get it

CCI customer teams