Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Installing server behind a proxy

2 months ago1 min read
Server v4.2
Server Admin
On This Page
  • Known limitations

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.

Configuring a proxy happens during Phase 2 - Core services.

Known limitations

  • The CircleCI hostname must be added to the no-proxy list because the following services: output processor and vm-service. The application and build-agent share a no-proxy list and are assumed to be behind the same firewall and therefore cannot have a proxy between them.

  • Some additional configuration is required to import orbs when installed behind a proxy. See Orbs on server docs for more information.

  • The JVM only accepts proxies that run over HTTP, not HTTPS, and therefore proxy URIs must be of the form http://user:password@host:port rather than https://user:password@host:port.

  • If your GitHub instance is running outside of the proxied environment (either GitHub.com or GitHub Enterprise), you must ensure that SSH traffic from CircleCI (inside the Kubernetes cluster) and from our Nomad node can reach your instance. Note that the default checkout step in a CircleCI job will fail to clone code and our ssh-keyscan of GitHub Enterprise will not work. While you may configure an SSH proxy, ssh-keyscan can NOT be proxied and instead will require you provide github.fingerprint when using GHE.

  • If you install server behind a proxy, you may need to provide a custom image for VM service. Visit the CircleCI Linux Image Builder repository for further information.

  • If object storage is outside the proxy, no job features that use object storage will work. This includes:

    • Artifacts

    • Test results

    • Cache save and restore

    • Workspaces

      Users can get around this restriction by setting environment variables on their jobs. For example:

      jobs:
  my-job:
    docker:
      - image: cimg/node:17.2.0
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        environment:
          HTTP_PROXY: http://proxy.example.com:3128
          HTTPS_PROXY: http://proxy.example.com:3128
          NO_PROXY: whatever.internal,10.0.1.2

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site