Remote Runners

This document provides complete instructions for deploying the Testifly Remote Runner on your infrastructure. The agent is distributed as a multi-arch Docker image, compatible with both x86_64 (Intel/AMD) and ARM64 (Apple Silicon/Graviton) architectures.

1. System Requirements

CPU: Minimum 0.5 Cores (Request), 1.0 Cores (Limit).
RAM: 5.8 GiB (Strict limit to ensure performance).
Network: Outbound access to testifly-hnapbwaxg6ddhyck.azurecr.io (Port 443).

2. Option A: Local / Single-Server Deployment (Docker Compose)

Use this method for standalone servers or local testing. No registry authentication is required as the image is public.

Step 1: Create folder

Create a local folder for the agent configuration and data, and navigate into it:

mkdir testifly-agent
cd testifly-agent

Step 2: Create a `.env` file

Store your credentials in a secure environment file in your project folder.

PROJECT_ID=your_project_id # take this from your Testifly dashboard url
API_KEY=your_api_key # take this from your Testifly dashboard (Settings > API Keys)
AGENT_NAME=your_agent_name # (e.g. "my-local-runner" or "our testing runners" - doesn't have be unique across your project)

Step 3: Create `docker-compose.yml`

Use the following configuration:

name: testifly

services:
  testifly-runner:
    image: testifly-hnapbwaxg6ddhyck.azurecr.io/testifly-remote-runner:latest
    restart: always
    env_file: .env
    volumes:
      # Persists data from the container to a 'data' folder in your current directory
      - ./data:/app/data
    extra_hosts:
      # Allows "localhost" inside the container to resolve to the host machine
      - 'localhost:host-gateway'
      # Recommended alias for cross-platform compatibility
      - 'host.docker.internal:host-gateway'
    deploy:
      resources:
        reservations:
          cpus: '0.5'
          memory: 6gb
        limits:
          cpus: '1.0'
          memory: 6gb

Step 4: Launch

To ensure you are running the latest version of the agent, always pull the latest image before starting:

docker-compose pull
docker-compose up -d

If you are switching from an old setup or changing configurations, run:

docker-compose down
docker-compose pull
docker-compose up -d

3. Option B: Enterprise Deployment (Kubernetes)

Use this method for production clusters requiring high availability and orchestration.

Step 1: Create a Namespace and Secret

First, create the namespace and a secret to securely store your API key.

# Create namespace
kubectl create namespace testifly

# Create secret for API Key
kubectl create secret generic testifly-auth \
  --from-literal=api-key=your_api_key_here \
  -n testifly

Step 2: Create the Deployment Manifest

Create a file named testifly-deployment.yaml.
For production, it is recommended to use a PersistentVolumeClaim (PVC) to store data and Secrets for sensitive keys.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: testifly-remote-runner
  namespace: testifly
spec:
  replicas: 1
  selector:
    matchLabels:
      app: testifly-runner
  template:
    metadata:
      labels:
        app: testifly-runner
    spec:
      containers:
        - name: runner
          image: testifly-hnapbwaxg6ddhyck.azurecr.io/testifly-remote-runner:latest
          imagePullPolicy: Always
          env:
            - name: PROJECT_ID
              value: 'your_project_id'
            - name: AGENT_NAME
              value: 'your_agent_name'
            - name: API_KEY
              # Recommended: Pull from Secret created in Step 1
              valueFrom:
                secretKeyRef:
                  name: testifly-auth
                  key: api-key
              # Alternatively, use a plain string (less secure):
              # value: "your_api_key_here"
          volumeMounts:
            - name: runner-data
              mountPath: /app/data
          resources:
            requests:
              cpu: '500m'
              memory: '5.8Gi'
            limits:
              cpu: '1000m'
              memory: '5.8Gi'
      volumes:
        - name: runner-data
          persistentVolumeClaim:
            claimName: testifly-pvc

Step 3: Apply to Cluster

kubectl apply -f testifly-deployment.yaml

4. Operations & Troubleshooting

Viewing Logs

Docker Compose: docker-compose logs -f
Kubernetes: kubectl logs -l app=testifly-runner -n testifly -f

Support

For technical assistance, please provide the Agent Name and recent log output to your Testifly support team at [email protected]. We’re happy to assist!.