Skip to content

Setup

How you set up Automator depends on your needs. You can either run it natively (if you use one of the supported operating systems) or in a Docker container. The following section is for the native installation; read the Docker Setup guide for Docker.

Tip

AVEQ also provides Ansible scripts for installing Automator on remote-managed devices. Ask us!

General Software Requirements

Surfmeter Automator requires the some additional software on your operating system. You should install this software manually according to the instructions of the respective software.

Tip

If you run Linux (Debian-based or Raspbian), you can also skip this section and use our setup.sh installation script to install the software automatically. Just follow that guide and you're all set. Read on if you want to manually install the software or run Surfmeter Automator on macOS or Windows.

We need the following command line software:

  • curl
  • unzip
  • tar with bzip2 support
  • jq

Ensure your system has these commands installed via:

sudo apt install curl unzip tar bzip2 jq

We recommend using Homebrew to install the software. If you don't have Homebrew installed, you can install it with the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then, install the software with the following commands:

brew install jq

We recommend using WSL (Windows Subsystem for Linux) to install the software. If you don't have WSL installed, you can install it with the following command:

wsl --install

Then, install the software with the following commands:

sudo apt install curl unzip tar bzip2 jq

Node.js

We tested Automator with Node v20 LTS. Node v18 still works, but it is recommended to use Node v20 LTS or higher.

To install Node.js, see the Node.js website. You may choose to use a package manager or install the software manually via its installer, depending on your needs.

Xvfb

This only works under Linux. We need Xvfb for running a headless display.

You need to install the xvfb, x11-utils, x11-xserver-utils packages, e.g. via apt:

sudo apt install xvfb x11-utils x11-xserver-utils

Chrome and ChromeDriver

You need:

For macOS or Linux, you can use the following npm command to install the latest matching ChromeDriver for your browser:

npm install \
    --unsafe-perm=true --allow-root -g \
    chromedriver \
    --detect_chromedriver_version \
    --chromedriver-force-download

Optional Additional Software

Surfmeter Automator may use the following third-party software if available. We cannot ship these with our default Docker installation for licensing reasons, so you need to install them yourself:

OS/User Requirements

You need an operating system that fulfills the requirements mentioned in the previous section.

Some further requirements are:

  • Certain dependencies may need sudo permissions in order to be installed (e.g. packages via apt). So you need a sudo user on your machine, at least for the installation process.

  • The Surfmeter Automator tool itself can and should run on a non-privileged user account. For the measurements themselves, no sudo access is needed, except for clearing DNS caches.

  • The OS must be connected to the Internet to register the software, perform measurements, and apply updates.

  • You must not use any proxy; usage with HTTP_PROXY and HTTPS_PROXY environment variables is untested at the moment. If you do use them, make sure they are exported in the same shell that you use to run Automator, and also available within cron jobs.

  • The path in which Automator is installed must not use any spaces.

Tip

Automator works on CLI-only systems via a headless mode (see Headless vs. GUI). You do not need a GUI or a display connected to the device. If you do want to use the GUI, you can do that, but it might interfere with your display while it's running.

For the installation, you can pick any location, but we recommend placing Surfmeter into a dedicated folder in the home folder of the user that will run the software. For instance, to create a folder surfmeter in the home folder, you can use the following commands:

cd ~
mkdir -p surfmeter

cd %USERPROFILE%
mkdir surfmeter

cd ~
mkdir surfmeter

Installation Files (Automated Download)

If you have received a list download commands from AVEQ, they will look like the following. Simply copy-paste these commands to extract the required installation files to the correct location.

# NOTE: this is just an example, do not run this as-is, refer to the commands you received from AVEQ
# wget -O extension-latest.zip ...
# mkdir -p surfmeter-lab
# unzip extension-latest.zip -d surfmeter-lab
#
# wget -O automator-latest.tar.bz2 ...
# mkdir -p surfmeter-lab-automator
# tar -xvf automator-latest.tar.bz2 -C surfmeter-lab-automator
#
# wget -O config-latest.tar.bz2 ...
# mkdir -p config
# tar -xvf config-latest.tar.bz2 -C config

After download and extraction of all three files, the file layout should be as follows:

~/surfmeter
    ├── config
    │   ├── automatorConfig.json           # the Automator configuration incl. measurement schedule
    │   ├── publicConfig.json              # the measurement configuration (optional)
    │   └── cloudLogging.json              # Google Cloud Log configuration (optional)
    ├── surfmeter-lab
    │   ├── app.html
    │   ├── assets
    │   ├── css
    │   ├── js
    │   ├── manifest.json
    │   ├── options.html
    │   ├── player.html
    │   └── popup.html
    └── surfmeter-lab-automator
        ├── setup.sh
        ├── run_vnc_server.sh
        ├── download_crx.sh
        ├── README.md
        ├── LICENSES.md
        ├── surfmeter-automator.cjs            # The main executable
        ├── surfmeter-automator-0.13.2.tar.bz2 # The original downloaded archive
        ├── surfmeter-automator-gui            # The GUI wrapper
        └── surfmeter-automator-headless       # The headless wrapper

Setup Script

Now, navigate to the folder wher you extracted the Automator files and run the setup script:

cd ~/surfmeter/surfmeter-lab-automator
sudo ./setup.sh

This will run the installation script, installing all necessary third-party dependencies via apt. It may take a while.

Warning

The setup script only works under Debian-based systems (including Raspbian). We can adapt the installation steps for other types of distributions if you need help. If you are under macOS, please install the dependencies manually as shown above.

To ensure that you can run the software without issues, please test the following command:

cd ~/surfmeter/surfmeter-lab-automator
node ./surfmeter-automator.cjs --help

This should output some usage notes. You're done!

We'll cover basic usage in the following section.