Getting Started

This guide covers all the ways to download, set up, and run the Synthetic Exporter, depending on your operating system and environment.

1. Download Pre-compiled Binaries (Linux & macOS)

Every time a new version is tagged, our automated pipeline builds and publishes pre-compiled binaries for Linux and macOS (both Intel and Apple Silicon/ARM64).

You can download the latest binary directly from the GitHub Releases page.

Once downloaded, simply make it executable and run it:

chmod +x synthetic-exporter-linux-amd64
./synthetic-exporter-linux-amd64 -config config.yaml

(Note: Playwright will automatically download the Chromium browser on the first run).

2. Docker (Cross-Platform / Recommended)

The repository provides a highly optimized, production-ready multi-stage Dockerfile. It uses dumb-init to handle zombie Chrome processes properly. This is the easiest way to run the exporter on any system.

Build and Run

docker build -t synthetic-exporter:latest .

Run the container and pass your environment variables. Make sure you mount your local config.yaml to /app/config.yaml:

docker run --rm -p 10050:10050 \
  -e APP_USERNAME="my_test_user" \
  -e APP_PASSWORD="my_secret_password" \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  synthetic-exporter:latest

Docker Compose

Alternatively, you can run the exporter using docker-compose. Create a docker-compose.yml file:

version: '3.8'

services:
  synthetic-exporter:
    image: synthetic-exporter:latest
    ports:
      - "10050:10050"
    environment:
      - APP_USERNAME=my_test_user
      - APP_PASSWORD=my_secret_password
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    restart: unless-stopped

Then simply run:

docker-compose up -d

3. Running Natively from Source (Windows / Dev)

If you are on Windows, or just want to run the code locally for development, you can easily compile and run the exporter manually from the source code. The exporter will automatically download the necessary headless Chromium browser for you upon starting.

Prerequisites:

• Install Go 1.22+ from golang.org.
• Git.

Setup Steps

1. Clone the repository:

   git clone https://github.com/aizik-fridman/synthetic-exporter.git
   cd synthetic-exporter

2. Prepare Environment Variables (Secrets):

   # Linux / macOS
   export APP_USERNAME="my_test_user"
   
   # Windows (PowerShell)
   $env:APP_USERNAME="my_test_user"

3. Run the Exporter: Download the Go dependencies and start the exporter:

   go mod download
   go run main.go -config config.yaml -listen-address :10050

Once running, you can access the exposed metrics at: http://localhost:10050/metrics.

CLI Flags

You can customize the exporter's behavior using the following CLI flags:

Flag	Default	Description
-config	config.yaml	Path to the YAML configuration file.
-listen-address	:10050	Address on which to expose the /metrics HTTP endpoint.
-check-interval	60s	The interval between background synthetic check runs (e.g., 30s, 1m).