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.

Set up a Linux local runner

Prepare machines

Review the following requirements for local runner build infrastructures:

  • There is a one-to-one relationship between Harness Docker Runners and Harness Delegates. If you need to run three local hosts, each host needs a runner and a delegate.
  • 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

  1. In Harness, go to Account Settings, select Account Resources, and then select Delegates.

    You can also create delegates at the project scope. In your Harness project, select Project Settings, and then select Delegates.

  2. Select New Delegate or Install Delegate.

  3. Select Docker.

  4. Enter a Delegate Name.

  5. Copy the delegate install command and modify it as follows:

    • Add --net=host to the first line.
    • Add -e DELEGATE_TAGS="DELEGATE_OS_ARCH", and replace DELEGATE_OS_ARCH with the tag corresponding to 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
  6. Run the modified install command on your build host machine.

tip

The delegate install command uses the default authentication token for your Harness account. If you want to use a different token, you can create a token and then specify it in the delegate install command:

  1. In Harness, go to Account Settings, then Account Resources, and then select Delegates.
  2. Select Tokens in the header, and then select New Token.
  3. Enter a token name and select Apply to generate a token.
  4. Copy the token and paste it in the value for DELEGATE_TOKEN.

For more information about delegates and delegate installation, go to Delegate installation overview.

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. (Optional) 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

Define build infrastructure

After configuring the host machine, you need to set the pipeline's build infrastructure.

Set up a macOS local runner

Prepare machines

Review the following requirements for local runner build infrastructures:

  • There is a one-to-one relationship between Harness Docker Runners and Harness Delegates. If you need to run three local hosts, each host needs a runner and a delegate.
  • 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

  1. In Harness, go to Account Settings, select Account Resources, and then select Delegates.

    You can also create delegates at the project scope. In your Harness project, select Project Settings, and then select Delegates.

  2. Select New Delegate or Install Delegate.

  3. Select Docker.

  4. Enter a Delegate Name.

  5. Copy the delegate install command and modify it as follows:

    • Add -e DELEGATE_TAGS="DELEGATE_OS_ARCH", and replace DELEGATE_OS_ARCH with the tag corresponding to your Docker environment's architecture: macos-amd64 or macos-arm64.
    • Add -e RUNNER_URL=http://host.docker.internal:3000.

    Here's an example of an install script for macOS amd64:

    docker run --cpus=1 --memory=2g \
    -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/gratis/log-service/ \
    -e DELEGATE_TAGS="macos-amd64" \
    -e RUNNER_URL=http://host.docker.internal:3000 \
    -e MANAGER_HOST_AND_PORT=https://app.harness.io/gratis harness/delegate:23.02.78306
  6. Run the modified install command on your build host machine.

tip

The delegate install command uses the default authentication token for your Harness account. If you want to use a different token, you can create a token and then specify it in the delegate install command:

  1. In Harness, go to Account Settings, then Account Resources, and then select Delegates.
  2. Select Tokens in the header, and then select New Token.
  3. Enter a token name and select Apply to generate a token.
  4. Copy the token and paste it in the value for DELEGATE_TOKEN.

For more information about delegates and delegate installation, go to Delegate installation overview.

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. (Optional) 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-darwin-amd64
  4. Start the runner binary. For example:

    ./harness-docker-runner-darwin-amd64 server
  5. If macOS Gatekeeper stops the installation because it can't check for malicious software, you need to modify Security & Privacy settings to allow this app to run.

    macOS Gatekeeper error message.

Allow the runner binary app to run
  1. Go to System Preferences and select Security & Privacy.
  2. On the General tab, select the lock to make changes.
  3. Select Allow next to the an app was blocked from loading message.
  4. Select OK.
  5. Select Open Anyway next to the not from an identified developer message.

  1. Select Open to confirm that you want to run the binary. If this window doesn't appear, rerun the binary start command.

Here is an example of the three commands to install the Darwin amd64 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-darwin-arm64
./harness-docker-runner-darwin-arm64 server

Define build infrastructure

After configuring the host machine, you need to set the pipeline's build infrastructure.

Set up a Windows local runner

Prepare machines

Review the following requirements for Windows local runner build infrastructures:

  • You need two machines for each build host:
    • A Windows machine where the Harness Docker Runner will run. This machine must have Docker for Windows installed. The Harness Docker Runner runs as an executable.
    • A Linux or macOS machine where the Harness Delegate will run. This machine must have Docker installed. The delegate runs as a container.
  • There is a one-to-one relationship between Harness Docker Runners and Harness Delegates. If you need to run three local hosts, each host needs a runner machine and a delegate machine.
  • 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.

Install the delegate

  1. In Harness, go to Account Settings, select Account Resources, and then select Delegates.

    You can also create delegates at the project scope. In your Harness project, select Project Settings, and then select Delegates.

  2. Select New Delegate or Install Delegate.

  3. Select Docker.

  4. Enter a Delegate Name.

  5. Copy the delegate install command and modify it as follows:

    • Add -e DELEGATE_TAGS="windows-amd64".
    • Add -e RUNNER_URL=http://WINDOWS_MACHINE_HOSTNAME_OR_IP:3000.
    warning

    The RUNNER_URL must point to the Windows machine where the Harness Docker Runner will run.

    Here's an example of the delegate install script for a local runner Windows build infrastructure:

    docker run --cpus=1 --memory=2g \
    -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/gratis/log-service/ \
    -e DELEGATE_TAGS="windows-amd64" \
    -e RUNNER_URL=http://WINDOWS_MACHINE_HOSTNAME_OR_IP:3000 \
    -e MANAGER_HOST_AND_PORT=https://app.harness.io/gratis harness/delegate:23.02.78306
  6. Run the modified install command on the Linux or macOS machine where you want to run the delegate.

tip

The delegate install command uses the default authentication token for your Harness account. If you want to use a different token, you can create a token and then specify it in the delegate install command:

  1. In Harness, go to Account Settings, then Account Resources, and then select Delegates.
  2. Select Tokens in the header, and then select New Token.
  3. Enter a token name and select Apply to generate a token.
  4. Copy the token and paste it in the value for DELEGATE_TOKEN.

For more information about delegates and delegate installation, go to Delegate installation overview.

Install the Harness Docker Runner

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

warning

Run the Harness Docker Runner executable on the Windows machine that you specified in the delegate's RUNNER_URL.

Use PowerShell to run these commands.

  1. On the target Windows machine where you want to run the Harness Docker Runner, download the Windows Harness Docker Runner executable.

  2. Open a terminal with Administrator privileges.

  3. (Optional) To use self-signed certificates, set 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:

    $env:CI_MOUNT_VOLUMES="C:\Users\installer\Downloads\certs;C:/Users/ContainerAdministrator/.jfrog/security/certs"
    info
  4. Run the following command to start the runner binary:

    harness-docker-runner-windows-amd64.exe server

Here is an example of the two commands to install the Windows amd64 Harness Docker Runner with self-signed certificates:

$env:CI_MOUNT_VOLUMES="C:\Users\installer\Downloads\certs;C:/Users/ContainerAdministrator/.jfrog/security/certs"
harness-docker-runner-windows-amd64.exe server

Define build infrastructure

After configuring the host machines, you need to set the pipeline's build infrastructure.

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.
delegate selectors

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.

Early access feature: Use delegate selectors for codebase tasks

Currently, delegate selectors for CI codebase tasks is behind the feature flag CI_CODEBASE_SELECTOR. Contact Harness Support to enable the feature.

By default, delegate selectors aren't applied to delegate-related CI codebase tasks.

With this feature flag enabled, Harness uses your delegate selectors for delegate-related codebase tasks. Delegate selection for these tasks takes precedence in order of pipeline selectors over connector selectors.

Troubleshoot local runner build infrastructure

Go to the CI Knowledge Base for questions and issues related to using a local runner build infrastructure, such as: