Installation

Candor should be installed with Docker. It is possible to run Candor on baremetal, but this method is not officially supported and only exists for development purposes. This guide assumes installation and basic familiarity with Docker.

The two first-party Docker images required can be found as follows:

• arraying/candor-dashboard for the dashboard.
• arraying/candor-runner for the runner.

This installation guide uses Linux (the only officially supported production platform) whereby the socket is presumed to be /var/run/docker.sock.

Networking & Security

In terms of networking, this installation guide creates the ecosystem on a single machine. Therefore, in order to wire together all components, a common network should be created:

docker network create candor-net

This guide will expose the dashboard locally, accessible through HTTP on port 3000 (though this can easily be changed). Thus, to serve traffic, the dashboard should be placed behind a reverse proxy and secured with a SSL certificate. It is recommended to use Nginx for a reverse proxy, and Let's Encrypt to obtain the SSL certificate. This guide provides an excellent introduction to Nginx reverse proxies and Let's Encrypt.

Note that Candor functions by mounting the Docker socket to the runner's container. This is done such that the runner is able to spin up containers for each pipeline step. However, this essentially gives the runner root access to your machine. Consequently, ensure that your runner is never accessible from outside your network (isolated communication with only the dashboard is recommended), and if this is unavoidable, use an extremely secure (read: long) token. For more information, see this post on exposing the socket.

Database

Candor uses PostgreSQL. A PostgreSQL server is not bundled with the dashboard or runner and must be set up by the system administrator manually. A simple example server installation using the PostgreSQL Docker image (that this guide is directly compatible with) is as follows:

docker container run -d --name candor-database \
  -e POSTGRES_PASSWORD=example \
  -e POSTGRES_USER=candor \
  -v /var/lib/postgresql/data \
  --net candor-net \
  postgres

Please note that this may or may not be production ready. In either case, please use a secure password.

Runner

A minimal installation for Linux/macOS:

docker container run -d --name candor-runner \
  -e RUNNER_TOKEN=your_super_secret_token \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/logs:/var/log/candor \
  --net candor-net \
  arraying/candor-runner

Note that on Windows, in a development environment with Docker Desktop and with the daemon exposed without TLS, replace the socket bind mount with -e RUNNER_DOCKER_HOST=tcp://host.docker.internal:2375. This could in theory also be set up with TLS, but requires a few additional caveats and environmental variables. For more information, see this document.

Furthermore, if this runner is running on a remote machine, ensure to expose its port with -p (and set up applicable firewall rules on the host machine). Then, specifying the network with --net is no longer required.

Dashboard

A minimal installation for most operating systems:

docker container run -it --name candor-dashboard \
  -e DASHBOARD_ORIGIN=http://localhost:3000 \
  -e DASHBOARD_COOKIE_SECRET=cookiemonster \
  -e RUNNER_TOKEN=your_super_secret_token \
  -e PGHOST=candor-database \
  -e PGPASSWORD=example \
  -v $(pwd)/logs:/var/log/candor \
  --net candor-net \
  -p 127.0.0.1:3000:3000 \
  arraying/candor-dashboard

This assumes a PostgreSQL database is accessible under the host specified in PGHOST. The implementation details of this are arbitrary, possibilities range from networking in a PostgreSQL container (as in this guide) to running the container on the host network and using a baremetal PostgreSQL server.

This will start an interactive session with the Candor CLI. The runner needs to be registered to the dashboard:

1. Select New runner.
2. Enter the name, for example, runner.
3. Select http:// as the protocol of the runner. (Note: remote runners should be using HTTPS).
4. The domain is candor-runner:3001.
5. If everything has been set up correctly, the runner should now be created.

Now, users and pipelines can be set up, or the session can be ended by detaching. To detach, the default Docker detach sequence can be used: CTRL-p followed by CTRL-q.

Archiving

To enable archiving, please provide the S3_* environment variables outlined in the Configuration page. These need to be provided to both the runner and dashboard.

A quick one-purpose S3 server can be created with Cloudserver:

# Download a working config to the current working directory.
curl https://gist.githubusercontent.com/Arraying/3c81d77939b3b1a9f36813a38342e5e3/raw -o candor_cloudserver_config.json
# Run the server.
docker run -d --name candor-s3 \
  -v $(pwd)/candor_cloudserver_config.json:/usr/src/app/config.json \
  -e S3DATA=multiple \
  -e S3BACKEND=file \
  -e SCALITY_ACCESS_KEY_ID=username \
  -e SCALITY_SECRET_ACCESS_KEY=password \
  --net candor-net \
  zenko/cloudserver

The config of Cloudserver dictates that the hostname should specify a region, hence the custom config. Since this guide uses the custom network, the hostname will be candor-s3 as per the container name. Consequently, the config specifies candor-s3 to map to eu-west-1. Unless you know what you are doing, with Cloudserver, the container name must be candor-s3 and region eu-west-1.

Configuration

This installation provides Candor with the default settings. It is important to give the container access to the host machine's Docker, such that it can spin up containers. How this is achieved depends on the installation, for more information see the Configuration page.

More advanced configuration can be found in the Configuration page. The environment variables provided there need to be specified when creating the runner(s) or dashboard.

A Note on docker-compose

Although Compose simplifies a lot of things (for example, automatic networking), there are several reasons why docker-compose is not the go-to installation method.

1. One Compose shoe does not fit all: this guide assumes a single dashboard and runner setup, in practice, this may vary.
2. Database definitions: some may be fond of an included database, others not.
3. Due to the CLI being interactive, if Compose is by accident started without -d, it is not possible to detach. Similarly, attaching and dettaching to the CLI becomes a bit more cumbersome.