Runners

Runners are nothing but Traceable CLI installed on your server as a service. You can download and install a runner either through Traceable Platform or as a service using an install.sh script is available on Traceable's download site or by using Helm chart.

Before you begin

Make a note of the following before proceeding with setting up Runner:

• A runner or CLI machine needs at least 4 CPUs and 16 GB of memory. This number may increase with an increase in the number of tests. Contact Traceable support for exact sizing by sending an email to support@traceable.ai.

• Ensure that the machine where you are installing the Runner can communicate with the APIs and Traceable Platform.

• DAST does not need an app to be instrumented, but an environment still needs to be created for DAST scan to create a default service and list APIs under it.

• Runners are not scoped by the environment. They are available for all environments.

• Ensure that you are assigned the Security admin or Account Owner role to start a runner. For more information about different roles, see Teams and roles - RBAC.

Option 1 — Download runner from UI

Navigate to Testing → Settings → Runners to start the runner configuration. Provide a name for the runner and the token. The binary CLI command and docker option are displayed. You can use either of the options to configure the runner on your server.

Copy the binary CLI command or the docker command to configure the runner.

By default, the binary command runs in the background. The Docker command given in the UI runs in the foreground in an interactive way. If you wish to run the Docker command in the background, use the following command. Replace the runner's name with the name of your runner:

docker run --rm -d -v ~/.traceable_docker:/app/userdata traceableai/traceable-cli:latest runner start --traceable-server api.traceable.ai --runner-name newrunner --token **** 

Following is an explanation of the Docker command:

• docker run is the command to run a Docker container.

• --rm removes the container automatically after it exits.

• -d runs the container in detached mode.

• -v ~/.traceable_docker:/app/userdata mounts the local directory ~/.traceable_docker to the /app/userdata directory inside the container. This allows the container to access and modify files in the local directory.

• traceableai/traceable-cli:latest specifies the image to use for the container.

• runner start runs the start command of the Traceable Runner program within the container.

• --traceable-server api.traceable.ai specifies the URL of the Traceable Server to connect to.

• --runner-name newrunner sets the name of the runner to “newrunner”.

• --token **** sets the authorization token required to connect to the Traceable Server.

Option 2 — Download and install Runner as a service

You can configure the runner as a systemd service. Download the installation script from Traceable's download site to configure Runner as a service. Navigate to cli → release → latest → install.sh to download the installation script.

Note

The install.sh script is supported on a Linux machine.

Run the script's help ( install.sh --help) command to know the various options.

You can run more than one runner on the same machine for both option 1 and option 2. For more information on how to run more than one runner on a single machine, contact Traceable support at support@traceable.ai. 

Option 3 — Install runner using Helm chart

Complete the following steps to install runner using Helm chart:

1. Enter the following command to add the repo:

   helm repo add traceableai https://helm.traceable.ai

2. Enter the following command to update the repo:

   helm repo update

Create values.yml file

Create a values.yml file based on the sample provided below. Make sure to add the correct values for traceableToken and traceableServer in the file.

replicaCount: 1

resources:
  limits:
    cpu: 4.0
    memory: 6Gi
  requests:
    cpu: 2.0
    memory: 6Gi

astRunnerArgs:
  # name of the runner
  name: traceable-runner-helm
  # traceableServer
  traceableServer: api.traceable.ai
  # traceableToken replace it with actual token value
  traceableToken: ""
  maxRetries: 1
  idleTimeout: 10
  # requestDelay delay between requests
  requestDelay: 0
  # Number of threads to run on
  threads: 1
  # log file name
  logfile: stdout
  # set log level
  loglevel: INFO

Enter the following command:

helm install <deployment_name>  traceableai/traceable-runner -f values.yaml