Skip to main content

Set up a local runner build infrastructure

You can define a CI build infrastructure on a Linux, macOS, or Windows host by installing a Harness Docker Delegate and local Harness Docker Runner. When the pipeline runs, the Harness Docker Runner runs the build actions in the environment where it is installed. The delegate handles communication between the Harness Platform and the Harness Docker Runner.

Local runner build infrastructure is recommended for small, limited builds, such as a one-off build on your local machine. Consider other build infrastructure options for builds-at-scale.

Docker delegate requirements​

The Harness Docker Delegate is limited by the total amount of memory and CPU on the local host. Builds can fail if the host runs out of CPU or memory when running multiple builds. The Harness Docker Delegate has the following system requirements:

  • Default 0.5 CPU.
  • Default 1.5GB. Ensure that you provide the minimum memory for the delegate and enough memory for the host/node system.
  • The machine where the delegate runs must have Docker installed.

Install the delegate and runner​

Install the delegate​

Use the following modifications along with the Docker instructions in Install the default delegate on Kubernetes or Docker:

  • Add --net=host to the first line.
  • Add -e DELEGATE_TAGS="<delegate-tag>". Use the tag for your Docker environment's architecture: linux-amd64 or linux-arm64.

Here's an example of an install script for Linux arm64:

docker run --cpus=1 --memory=2g --net=host \
  -e DELEGATE_NAME=docker-delegate \
  -e NEXT_GEN="true" \
  -e DELEGATE_TYPE="DOCKER" \
  -e ACCOUNT_ID=H5W8iol5TNWc4G9h5A2MXg \
  -e DELEGATE_TOKEN=YOUR_API_TOKEN \
  -e LOG_STREAMING_SERVICE_URL=https://app.harness.io/log-service/ \
  -e DELEGATE_TAGS="linux-arm64" \
  -e MANAGER_HOST_AND_PORT=https://app.harness.io/ harness/delegate:23.02.78306

Make sure to create the delegate at the appropriate scope, such as the project level or account level.

Install the Harness Docker Runner​

The Harness Docker Runner service performs the build work. The delegate needs the runner to run CI builds.

  1. Download a Harness Docker Runner executable corresponding to your build farm's OS and architecture.

  2. To use self-signed certificates, export CI_MOUNT_VOLUMES along with a comma-separated list of source paths and destination paths formatted as path/to/source:path/to/destination, for example:

    export CI_MOUNT_VOLUMES="[path/to/local/cert];/etc/ssl/certs/ca-certificates.crt,[path/to/local/cert2];/etc/ssl/certs/cacerts.pem"
    info

    If your pipelines have STO scan steps, review the additional requirements for adding custom artifacts to STO pipelines.

  3. Enable execution permissions for the Runner. For example:

    sudo chmod +x harness-docker-runner-linux-arm64

  4. Start the runner binary. For example:

    sudo ./harness-docker-runner-linux-arm64 server

Here is an example of the three commands to install the Linux arm64 Harness Docker Runner with self-signed certificates:

export CI_MOUNT_VOLUMES="[path/to/local/cert];/etc/ssl/certs/cacerts.pem"
sudo chmod +x harness-docker-runner-linux-arm64
./harness-docker-runner-linux-arm64 server

Set the pipeline's build infrastructure​

Edit the CI pipeline where you want to use the local runner build infrastructure.

  1. In the pipeline's Build stage, select the Infrastructure tab.
  2. Select Local for the Infrastructure.
  3. Select the relevant Operating System and Architecture.
  4. Save your pipeline.
tip

Although you must install a delegate to use the local runner build infrastructure, you can choose to use a different delegate for executions and cleanups in individual pipelines or stages. To do this, use pipeline-level delegate selectors or stage-level delegate selectors.

Delegate selections take precedence in the following order:

  1. Stage
  2. Pipeline
  3. Platform (build machine delegate)

This means that if delegate selectors are present at the pipeline and stage levels, then these selections override the platform delegate, which is the delegate that you installed on the build machine. If a stage has a stage-level delegate selector, then it uses that delegate. Stages that don't have stage-level delegate selectors use the pipeline-level selector, if present, or the platform delegate.

For example, assume you have a pipeline with three stages called alpha, beta, and gamma. If you specify a stage-level delegate selector on alpha and you don't specify a pipeline-level delegate selector, then alpha uses the stage-level delegate, and the other stages (beta and gamma) use the platform delegate.

Troubleshooting the delegate connection​

The delegate should connect to your instance after you finish the installation workflow above. If the delegate does not connect after a few minutes, run the following commands to check the status:

docker ps
docker logs --follow <docker-delegate-container-id>

The container ID should be the container with image name harness/delegate:latest.

Successful setup is indicated by a message such as Finished downloading delegate jar version 1.0.77221-000 in 168 seconds.