Skip to main content
Version: 2.0 (Preview)

Setup (Docker)

This guide runs Automator in a Docker container. The image contains Automator, the browser, and all the tools for the measurements. To install Automator directly on a Linux machine, see Setup.

Prerequisites​

Install Docker Desktop or Docker Engine, and make sure that the docker and docker compose commands are available.

To access our Docker image, you need to log in to our registry once on each machine. Docker stores the login, and it does not expire. To get the command for this:

  1. Open Clients > Create Client (https://surfmeter-server.<customer>-analytics.aveq.info/app/clients/new) in your Surfmeter Dashboard, where <customer> stands for the name of your organization. Viewers have no access to this page. If you are a viewer, ask an editor or administrator of your organization.
  2. Select Surfmeter Automator v2, and turn on Use Docker.
  3. Copy and run the login command. The page also shows the current version of the image, the command to pull it, a ready-made docker-compose.yml file, and the commands for setting the label and tags.

The Clients > Software Downloads page (/app/clients/software) also provides these commands and the Compose file, but does not fill in a registration key.

If the page does not show a login command, contact us to get access.

Registration Key and Server Address​

When the container starts for the first time, it registers itself as a new client with your Surfmeter server. It needs two values for this, which you set in the Compose file:

  • SURFMETER_DEFAULT_SERVER is the address of your Surfmeter server. This is the address of your Surfmeter Dashboard without the path, such as https://surfmeter-server.<customer>-analytics.aveq.info.
  • SURFMETER_DEFAULT_REGISTRATION_KEY allows the client to register, and determines what it may measure. To get one, open Registration Keys in the dashboard, select a key, and copy its value from the detail page. Administrators can also create a new key there. If you cannot get a key, ask AVEQ.

The Compose file on the Create Client page has both values filled in. The one on the Software Downloads page has the server address, and you only need to replace <REGISTRATION_KEY>.

The key must have registrations left, and if it is limited to certain client types, these must include Surfmeter Automator.

Set both values before the first start

If SURFMETER_DEFAULT_SERVER is missing, the container registers with AVEQ's default server. If registration fails, for example because of a wrong key or server address, the container keeps restarting until you fix the problem. Run docker compose logs to see the error.

The container only uses these values for its first registration, which is then stored in the volume. Changing them later has no effect on a registered client.

Starting the Container​

Create a directory, for example ~/surfmeter-docker, with a file called docker-compose.yml. Copy this file from the dashboard, or use this example and fill in the registration key and server address:

name: surfmeter-lab-automator

services:
  surfmeter:
    image: europe-west3-docker.pkg.dev/aveq-storage/surfmeter/surfmeter-lab-automator:<version> # (1)
    container_name: surfmeter
    restart: unless-stopped
    stop_grace_period: 30s # (2)
    logging: # (3)
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    cap_add: # (4)
      - NET_ADMIN
      - NET_RAW
    volumes:
      - surfmeter:/home/surfmeter/.surfmeter # (5)
    environment: # (6)
      SURFMETER_AUTO_REGISTER: "1"
      SURFMETER_DEFAULT_REGISTRATION_KEY: "<REGISTRATION_KEY>" # (7)
      SURFMETER_DEFAULT_SERVER: "https://surfmeter-server.<customer>-analytics.aveq.info" # (8)
      SURFMETER_AUTO_START_DAEMON: "1"
    ports: # (9)
      - "127.0.0.1:5123:5123"
      - "127.0.0.1:8080:80"

volumes:
  surfmeter:
  1. The image to use. Replace <version> with the version shown in the dashboard, such as 2.0.0.
  2. When stopping, the daemon waits up to 15 seconds for running studies. The 30-second grace period allows this to finish before Docker kills the container.
  3. All services log JSON lines to the container output. This setting rotates the log on the host.
  4. These capabilities are required for capturing network traffic using tcpdump.
  5. The volume keeps the registration, configuration, unsent results, logs, and other files when the container is recreated.
  6. These settings register the container on its first start, and start the scheduling daemon. See all environment variables.
  7. Replace this with your registration key.
  8. Replace this with the address of your Surfmeter server.
  9. The ports of the VNC server and the health check API.

Then, start the container:

docker compose up -d

Check that it is running and registered:

docker compose ps
docker exec --user surfmeter surfmeter surfmeter auth status --verify

If you deploy the same Compose file on multiple machines, ensure that the registration key can be used multiple times. You can configure this in the dashboard, under Registration Keys.

Important: Assign a configuration to start measuring

The new client gets its configuration from your Surfmeter server. Assign a configuration to it, unless one is assigned automatically. The container picks it up within 15 minutes.

Running Commands in the Container​

Run any surfmeter command with docker exec. The examples in this documentation show the command only. Prefix them like this:

docker exec --user surfmeter surfmeter surfmeter daemon status
docker exec --user surfmeter surfmeter surfmeter study list

The first surfmeter is the user, the second the name of the container, and the third the program.

To get a shell inside the container, run:

docker exec --user surfmeter -it surfmeter /bin/bash

Environment Variables​

  • SURFMETER_AUTO_REGISTER: set to 1 to register the client on the first start
  • SURFMETER_DEFAULT_REGISTRATION_KEY: the registration key for the automatic registration
  • SURFMETER_DEFAULT_SERVER: the Surfmeter server to register with, as a full address or a short name such as <customer>-analytics
  • SURFMETER_AUTO_START_DAEMON: set to 1 to run the scheduling daemon. Without it, nothing is scheduled, and you can only start measurements by hand.
  • SURFMETER_DISABLE_CONFIG_UPDATE: set to 1 to stop downloading the configuration from the server, for example if you mount it into the container
  • SURFMETER_ENABLE_VNC: set to 1 to run a VNC server
  • SURFMETER_PERSISTENT_DISPLAY: set to 1 to keep a virtual display running in the container. This is implied by SURFMETER_ENABLE_VNC.
  • SURFMETER_DISPLAY: the number of the virtual display (default: :123)
  • SURFMETER_DISPLAY_RESOLUTION: the resolution of the virtual display (default: 1920x1080x24)
  • SURFMETER_DISABLE_PULSEAUDIO: set to 1 to disable PulseAudio
  • SURFMETER_DISABLE_SYSTEM_STATUS: set to 1 to disable the collection and reporting of CPU, memory, filesystem, and connection status
  • LOG_LEVEL: the log level

You can also override any command-line option with an environment variable.

Using a Local Configuration​

To maintain the configuration yourself instead of through the dashboard, mount it into the container and disable the download from the server:

services:
  surfmeter:
    # ...
    volumes:
      - surfmeter:/home/surfmeter/.surfmeter
      - ./config:/home/surfmeter/.surfmeter/config
    environment:
      # ...
      SURFMETER_DISABLE_CONFIG_UPDATE: "1"

The config directory contains your automatorConfig.json and publicConfig.json. See Local Configuration for more information.

Updating the Container​

To update the container, change <version> in the image line of the Compose file to the new version shown in the dashboard. Then, pull the image and recreate the container:

docker compose pull
docker compose up -d

The registration and the data are kept in the volume.

The command surfmeter update does not work in a container.

Stopping the Container​

Stop the container with docker compose stop, or remove it with docker compose down.

Deleting the volume removes the client registration

Adding --volumes also deletes the registration, configuration, and any unsent results stored in the volume. To return the license, run surfmeter auth unregister in the container before removing it.

To remove the container and its volume, run:

docker compose down --volumes

Exposed Ports​

The container exposes port 5123 for VNC, and port 80 for a health check API, which the Compose file above makes available at port 8080 of the host. By default, the ports are only available on the host itself. If you change 127.0.0.1 to 0.0.0.0, they can be reached from any network interface of the host. In that case, make sure that a firewall protects them.

VNC​

See VNC Connection.

Health Check​

GET /v1/health returns information like this:

{
  "status": "green",
  "checks": { "freeMemory": true, "freeDiskSpace": true },
  "details": {},
  "isRegistered": true
}

The status is red if any of these conditions apply:

  • Free memory is 100 MB or less.
  • Free disk space is 1000 MB or less.
  • The persistent virtual display is enabled but not running.
  • The daemon is enabled but does not respond.

Docker uses the same check to report the health of the container.

Using the Host GPU (Optional)​

On a Linux amd64 host with a GPU that exposes /dev/dri devices, you can enable GPU rendering in the browser. The image includes the graphics drivers.

Find the IDs of the render and video groups on the host:

getent group render video

Pass the GPU to the container, using the IDs from the previous command:

services:
  surfmeter:
    # ...
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - "<render-group-id>"
      - "<video-group-id>"

Finally, set the options for GPU rendering in the schedule config.