# 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 [support@testifly.dev](mailto:support@testifly.dev). We’re happy to assist!