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!

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. To add your user to the sudo group, you can use the following command:

    sudo usermod -aG sudo $USER

    You need to log out and log in again for the changes to take effect.

  • 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. In other words, please do not run Surfmeter as root.

  • 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 -o 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!

Manual Installation

Follow the below steps to manually install the software.

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

Chromium Browser and Chromium WebDriver

You need a compatible browser and WebDriver. We support:

Chromium Installation

To install Chromium and ChromiumDriver via apt, you can use the following command:

sudo apt install chromium chromium-driver

Chrome for Testing Installation

Chrome for Testing requires special setup because ChromeDriver doesn't search $PATH - it only looks in hardcoded locations like /usr/local/bin/chrome, /usr/bin/google-chrome, etc. You have three options to install Chrome for Testing correctly:

We provide a script that downloads and installs Chrome for Testing correctly:

cd ~/surfmeter/surfmeter-lab-automator
sudo ./util/install_chrome_for_testing.sh

This installs both Chrome for Testing and ChromeDriver to /usr/local/bin.

If you've already downloaded Chrome for Testing using @puppeteer/browsers or manually:

npx @puppeteer/browsers install chrome@latest --path ~/puppeteer
# prints, e.g.:
# chrome@144.0.7500.0 /home/youruser/puppeteer/chrome/linux-144.0.7500.0/chrome-linux64/chrome
npx @puppeteer/browsers install chromedriver@latest --path ~/puppeteer
# prints, e.g.:
# chromedriver@144.0.7500.0 /home/werner/puppeteer/chromedriver/linux-144.0.7500.0/chromedriver-linux64/chromedriver

# link your Chrome for Testing binary to /usr/local/bin
sudo ln -sf /home/youruser/puppeteer/chrome/linux-144.0.7500.0/chrome-linux64/chrome /usr/local/bin/google-chrome
sudo ln -sf /home/youruser/puppeteer/chrome/linux-144.0.7500.0/chromedriver/linux64/chromedriver /usr/local/bin/chromedriver

Always specify the binary paths when running Automator:

surfmeter-automator --chromeBinary=/path/to/chrome --chromeDriverBinary=/path/to/chromedriver checkRegistration

Or set it in your automatorConfig.json in:

{
    "globalScheduleSettings": {
        "options": {
            "chromeBinary": "/path/to/chrome",
            "chromeDriverBinary": "/path/to/chromedriver"
        }
    }
}

Optional Additional Software

Surfmeter Automator may use the following third-party software if available. These are already included in the Docker image.

Uninstalling

To uninstall Surfmeter Automator, you can run the following command:

rm -rf ~/surfmeter ~/.surfmeter

To stop the Xvfb server, if you installed the service, you can run the following command:

systemctl --user stop xvfb-surfmeter.service
rm -f $HOME/.config/systemd/user/xvfb-surfmeter.service
systemctl --user daemon-reload

Optionally, you may remove the additional software that was installed by the setup script, such as ffmpeg, Node.js, Chromium, ChromeDriver, and xvfb.

sudo apt remove ffmpeg nodejs chromium chromium-driver xvfb

We'll cover basic usage in the following section.