Running Multiple Instances

There are two ways of running several measurements at the same time on one machine:

• Run them in parallel on one client. This works without any setup, natively and in Docker.
• Run several clients, each with its own registration and configuration. This is easiest with Docker.

Parallel Runs on One Client

To run several studies together, pass them to one command. See Starting Parallel Studies.

surfmeter study start --studyId STUDY_YOUTUBE --studyId STUDY_FASTCOM

Several surfmeter processes can run at the same time, natively or in a container. Each browser gets its own temporary profile. The processes share a client registration and configuration:

• You can run a study by hand to test something, while the daemon runs its schedule.
• The daemon can run any number of different schedule entries at the same time, but runs of the same entry cannot overlap. See Scheduling Studies.

Start separate commands yourself only if the studies need different options, such as their own timeouts or report files, or if they do not start at the same time. The options of one command apply to all of its studies.

Parallel runs can affect measurement results

All runs share the machine's CPU, memory, and network connection. Plan for 1-2 CPU cores and 2-4 GB of memory per browser. A packet capture also records traffic from other runs on the machine.

Use a separate display for each recording

With the default display mode, all browsers use the permanent virtual display, if it is running. Use --display xvfb to give each run its own display when recording the screen. See Display Modes.

Multiple Clients with Docker

If each instance should be a separate client in the dashboard, with its own configuration, run one container per client. Set up Docker according to our setup guide first.

Each service needs a unique container name, unique host ports, and its own volume. Here is an example with two instances:

name: surfmeter-lab-automator

x-surfmeter: &surfmeter
  image: europe-west3-docker.pkg.dev/aveq-storage/surfmeter/surfmeter-lab-automator:<version>
  restart: unless-stopped
  stop_grace_period: 30s
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "5"
  cap_add:
    - NET_ADMIN
    - NET_RAW
  environment: &surfmeter-env
    SURFMETER_AUTO_REGISTER: "1"
    SURFMETER_DEFAULT_REGISTRATION_KEY: "<REGISTRATION_KEY>"
    SURFMETER_DEFAULT_SERVER: "https://surfmeter-server.<customer>-analytics.aveq.info"
    SURFMETER_AUTO_START_DAEMON: "1"

services:
  surfmeter-1:
    <<: *surfmeter
    container_name: surfmeter-1
    volumes:
      - surfmeter-1:/home/surfmeter/.surfmeter # (1)
    ports:
      - "127.0.0.1:5123:5123"
      - "127.0.0.1:8080:80"

  surfmeter-2:
    <<: *surfmeter
    container_name: surfmeter-2
    volumes:
      - surfmeter-2:/home/surfmeter/.surfmeter
    ports: # (2)
      - "127.0.0.1:5124:5123"
      - "127.0.0.1:8081:80"

volumes:
  surfmeter-1:
  surfmeter-2:

1. Each instance needs its own volume, as this stores its registration.
2. Each instance uses different host ports. The ports inside the container must remain the same.

Fill in your registration key and server address, and make sure that the key can be used for all instances. Then, start them:

docker compose up -d

To run a command in all instances, use a loop in the directory of the docker-compose.yml file:

for service in $(docker compose ps --services | grep surfmeter); do
    echo "--- $service"
    docker compose exec --user surfmeter "$service" surfmeter daemon status
done

Multiple Clients without Docker

The environment variable SURFMETER_STORAGE_DIR gives a command its own registration and configuration. However, the setup script installs only one daemon, for the default directory. We recommend Docker for this.