Runners

Runners are nothing but Traceable CLI installed on your server as a service. You can download and install a runner either through the Traceable Platform or as a service using an install.sh script 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 needs at least 2 CPUs and 4 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: 2.0
    memory: 4Gi
  requests:
    cpu: 2.0
    memory: 4Gi

astRunnerArgs:
  name: traceable-runner-helm   # Name of the runner
  traceableServer: api.traceable.ai   # Traceable Server
  traceableToken: ""   # Replace this with actual token value
  maxRetries: 1   # Number of Request Retries
  idleTimeout: 10   # Idle Timeout before aborting a scan
  requestDelay: 0   # Request delay delay between requests
  threads: 20   # Number of threads to run on
  logfile: stdout   # Log file name
  loglevel: INFO   # Set log level

Enter the following command:

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