Start Building for Free

Frequently Asked Questions

Server v2.x
On This Page

This document is intended for system administrators of self-hosted installations of CircleCI Server.

This chapter answers frequently asked questions and provides installation troubleshooting tips.

Can I move or change my GitHub Enterprise URL without downtime?

No, because of the nature of CircleCI integration with GitHub authentication, you should not change the domain of your GHE instance after CircleCI is in production. Redeploying GitHub without will result in a corrupted CircleCI instance. Contact support if you plan to move your GitHub instance.

Can I monitor available build containers?

Yes, refer to the Introduction to Nomad Cluster Operation section for details. Refer to the Monitoring Your Installation section for how to enable additional container monitoring for AWS.

How do I provision admin users?

The first user who logs in to the CircleCI application will automatically be designated an admin user. Options for designating additional admin users are found under the Users page in the Admin section at https://[domain-to-your-installation]/admin/users.

How can I gracefully shutdown Nomad Clients?

Refer to the Introduction to Nomad Cluster Operation chapter for details.

Why is Test GitHub Authentication failing?

This means that the GitHub Enterprise server is not returning the intermediate SSL certificates. Check your GitHub Enterprise instance with – it may report some missing intermediate certs. You can use commands like openssl to get the full certificate chain for your server.

In some cases authentication fails when returning to the configuration page after it was successfully set up once. This is because the secret is encrypted, so when returning checking it will fail.

How can I use HTTPS to access CircleCI?

While CircleCI creates a self-signed cert when starting up, that certificate only applies to the management console and not the CircleCI product itself. If you want to use HTTPS, you’ll have to provide certificates to use under the Privacy section of the settings in the management console.

Why doesn’t terraform destroy every resource?

CircleCI sets the services box to have termination protection in AWS and also writes to an s3 bucket. If you want terraform to destroy every resource, you’ll have to either manually delete the instance, or turn off termination protection in the file. You’ll also need to empty the s3 bucket that was created as part of the terraform install.

Do the Nomad Clients store any state?

They can be torn down without worry as they don’t persist any data.

How do I verify TLS settings are failing?

Make sure that your keys are in unencrypted PEM format, and that the certificate includes the entire chain of trust as follows:

intermediate 1
intermediate 2

How do I debug the Management Console (Replicated)?

The CircleCI management console is powered by Replicated. If you are experiencing any issues with the Management Console, here are a few ways to debug it:

1. Check you have Replicated installed

First, make sure you have the CLI tool for Replicated installed by running the following:

replicated -version

2. Restart Replicated and the CircleCI app

Try restarting Replicated services. You can do this by running the following commands on the service box, for Ubuntu 14.04:

sudo service replicated-ui restart
sudo service replicated restart
sudo service replicated-operator restart

For Ubuntu 16.04, run the following commands:

sudo systemctl restart replicated-ui
sudo systemctl restart replicated
sudo systemctl restart replicated-operator

Then try restarting the CircleCI app: go to your services box admin (for example, <your-circleci-hostname>.com:8800) and try restarting with "Stop Now" and "Start Now".

3. Try to log into Replicated

Try logging in to Replicated. You can do this by running the following command on the service box. You will be asked to enter your password - the same one used to unlock the Management Console (i.e. <your-circleci-hostname>.com:8800 ).

replicated login

If you could login, then run the following command and send the output to us at so we can help diagnose what is causing the problem you are experiencing.

sudo replicated apps

If you were seeing the following error: request returned Unauthorized for API route this could be because you are not logged into Replicated, so please check if you are still getting the error after a successful login.

4. Check Replicated logs

You can find Replicated logs on the Services machine under /var/log/replicated.

5. Check what Docker containers are currently running

Replicated starts many Docker containers to run CircleCI server v2.x, so it can be useful to check what containers are running.

To check what containers are currently running, run sudo docker ps and you should see something similar to this output:

$ sudo docker ps
CONTAINER ID        IMAGE                                                                 COMMAND                  CREATED             STATUS              PORTS                                                                                                                                                    NAMES
eb2970306859              "circleci-service-run"   26 hours
ago        Up 26 hours>80/tcp,>443/tcp,>3000/tcp,>6010/tcp,>8585/tcp                                  api-service

01d26714f5f5    "/service/docker-ent…"   26 hours
ago        Up 26 hours>9998/tcp,>80/tcp,>443/tcp,>3000/tcp,>8585/tcp                                   workflows-conductor

0cc6e4248cfb      "/service/docker-ent…"   26 hours
ago        Up 26 hours>3000/tcp

9e6efc98b7d6              "circleci-service-run"   26 hours
ago        Up 26 hours>4261/tcp                                                                                                                                   cron-service
8c40bd1cecf6      "/service/docker-ent…"   26 hours
ago        Up 26 hours>3145/tcp,>8010/tcp,>8090/tcp                                                                                   federations-service
71c71941684f         "./docker-entrypoint…"   26 hours
ago        Up 26 hours>2718/tcp,>3011/tcp,>8091/tcp                                                                                   contexts-service
71ffeb230a90           "/service/docker-ent…"   26 hours
ago        Up 26 hours>3000/tcp                                                                                                                                   domain-service
eb22d3c10dd8         "circleci-service-run"   26 hours
ago        Up 26 hours                                                                                                                                                                  audit-log-service
243d9082e35c               "/docker-entrypoint.…"   26 hours
ago        Up 26 hours>80/tcp,>443/tcp,>4434/tcp                                                                                         frontend
af34ca3346a7       "circleci-service-run"   26 hours
ago        Up 26 hours                                                                                                                                                                  picard-dispatcher
fb0ee1b02d48               "vm-service-service-…"   26 hours ago        Up 26 hours>3000/tcp                                                                                                                                   vm-service
3708dc80c63e                "/scaler-entrypoint.…"   26 hours
ago        Up 26 hours>5432/tcp                                                                                                                                  vm-scaler
77bc9d0b4ac9                    "docker-entrypoint.s…"   26 hours
ago        Up 26 hours>5432/tcp                                                                                                                                  vm-gc
4b02f202a05d       "output-processor-se…"   26 hours
ago        Up 26 hours>8585/tcp,>80/tcp,>443/tcp                                                                                    picard-output-processor
b8f982d32989               "/docker-entrypoint.…"   26 hours ago        Up 26 hours>80/tcp,>443/tcp,>4434/tcp                                                                                   dispatcher
601c363a0c38               "/docker-entrypoint.…"   26 hours
ago        Up 26 hours>80/tcp,>443/tcp,>4434/tcp                                                                                   legacy-notifier
f2190c5f3aa9                                 "/"         26 hours
ago        Up 26 hours>27017/tcp                                                                                                                                 mongo
3cbbd959f42e                                     "/telegraf-entrypoin…"   26 hours
ago        Up 26 hours>8125/udp,>8092/udp,>8094/tcp                                                                                 telegraf
15b090e8cc02             "circleci-service-run"   26 hours
ago        Up 26 hours                                                                                                                                                                  picard-scheduler
fb967bd3bca0                    "/"   26 hours
ago        Up 26 hours>4646-4648/tcp                                                                                                                         nomad
7e0743ee2bfc             "circleci-service-run"   26 hours
ago        Up 26 hours>2719/tcp,>3012/tcp                                                                                                           test-results
0a95802c87dc                   "/docker-entrypoint.…"   26 hours
ago        Up 26 hours>4567/tcp,>8080/tcp                                                                                                           slanger
ca445870a057     "docker-entrypoint.s…"   26 hours
ago        Up 26 hours>5432/tcp                                                                                                                                   postgres
a563a228a93a        "/server-ready-agent"    26 hours
ago        Up 26 hours>8000/tcp                                                                                                                                   ready-agent
d6f9aaae5cf2        "bash -c /src/entryp…"   26 hours
ago        Up 26 hours                                                                                                                                                                  usage-stats
086a53d9a1a5                 "/usr/bin/supervisor…"   26 hours
ago        Up 26 hours>2443/tcp,>8125/udp                                                                                                         replicated-statsd
cc5e062844be       "/usr/local/bin/pyth…"   26 hours
ago        Up 26 hours                                                                                                                                                                  musing_volhard
9609f04c2203      "docker-entrypoint.s…"   26 hours
ago        Up 26 hours>5672/tcp,>15672/tcp,>4369/tcp,>5671/tcp,>15671/tcp,>25672/tcp   rabbitmq
2bc0cfe43639                             "crond -f"               26 hours
ago        Up 26 hours                                                                                                                                                                  hardcore_cray
79aa857e23b4                   "./docker-entrypoint…"   26 hours
ago        Up 26 hours>8200-8201/tcp                                                                                                                         vault-cci
b3e317c9d62f                                       "docker-entrypoint.s…"   26 hours
ago        Up 26 hours>6379/tcp                                                                                                                                   redis
f2d3f77891f0              "/usr/local/bin/dock…"   26 hours
ago        Up 26 hours                                                                                                                                                                  nomad-metrics
1947a7038f24                                       "docker-entrypoint.s…"   26 hours
ago        Up 26 hours>6379/tcp                                                                                                                                  slanger-redis
3899237a5782                       "/docker-entrypoint.…"   26 hours
ago        Up 26 hours>25/tcp                                                                                                                                     exim
97ebdb831a7e                        "/src/replicated-aud…"   26 hours
ago        Up 26 hours         3000/tcp                                                                                                                                                 retraced-processor
a0b806f3fad2                        "/src/replicated-aud…"   26 hours
ago        Up 26 hours>3000/tcp                                                                                                                               retraced-api
19dec5045f6e                        "/bin/sh -c '/usr/lo…"   26 hours
ago        Up 26 hours         3000/tcp                                                                                                                                                 retraced-cron
7b83a3a193da       "docker-entrypoint.s…"   26 hours
ago        Up 26 hours         5432/tcp                                                                                                                                                 retraced-postgres
029e8f454890   "/bin/sh -c nsqd"        26 hours
ago        Up 26 hours         4150-4151/tcp, 4160-4161/tcp, 4170-4171/tcp                                                                                                              retraced-nsqd
500619f53e80                        "/usr/bin/replicated…"   26 hours
ago        Up 26 hours                                                                                                                                                                  replicated-operator
e1c752b4bd6c                                 " -d"       26 hours
ago        Up 26 hours>9874-9879/tcp                                                                                                                         replicated
1668846c1c7a                              "/usr/bin/replicated…"   26 hours
ago        Up 26 hours>8800/tcp                                                                                                                                   replicated-ui
f958cf3e8762                         "/usr/bin/premkit da…"   3 weeks
ago         Up 26 hours         80/tcp, 443/tcp, 2080/tcp,>2443/tcp                                                                                                        replicated-premkit

Providing with the output of sudo docker ps from the Services machine will help us diagnose the cause of your problem.

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.