Setup (Docker)¶

This describes the Docker-based installation of Automator.

Prerequisites¶

Docker¶

You need to first install Docker per the official instructions.

There are two ways to install Docker:

Docker Desktop - easy, recommended for lab or desktop usage
Docker Engine - more advanced, recommended for production deployments

If you are using Docker Engine, you need to manually install docker compose from the Docker documentation.

After installation make sure that the docker and docker compose commands are available.

GitLab Account¶

To access our Docker image, you need an account on https://git.aveq.info — our GitLab instance.

There are two ways to access the Docker registry:

Use the guest account we send you.
Use your own GitLab account.

Follow the instructions for the option you prefer.

Use the guest account we send youUse your own GitLab account

If you have received a guest account from AVEQ, you can use the credentials we sent you. This contains a username and a token. Your username will be like <customer>-docker.

To connect to our Docker registry, you need a Personal Access Token (PAT) from GitLab. Please do the following:

Access your GitLab user account and create a personal access token (PAT): https://git.aveq.info/-/profile/personal_access_tokens.
Enter a unique name for the token and in the list of checkboxes, check the read_registry type of access.

Once you click the button, a token will be displayed above. Copy the token and save it somewhere safe. It will not be shown again, and we cannot restore it for you.

Pulling the Image¶

Pull the Docker image from the Docker registry. Log into the registry with:

docker login registry.aveq.info

As username, enter your username, and as password, enter the username and token we sent to you (or the PAT you created yourself).

Pulling the image can be done with the following command — but replace the yourcustomername part with your customer ID, which we sent to you:

CUSTOMER=yourcustomername
docker pull registry.aveq.info/$CUSTOMER/surfmeter-lab-automator:$CUSTOMER-latest

Contact us if you need help.

If you ever need to update the image (which we recommend you do regularly), you can pull the latest version with the same command. Just note that any running containers will not be updated automatically — they will continue to run the old version and need to be restarted to pick up the new version.

Excursion: Mounting Directories in Docker¶

This is a technical section

Skip this section if you are not interested in the details of how Docker works.

Our Surfmeter Docker container is meant to run in the background (detached), and should be always running. (There are other types of applications where you would want to run a container in the foreground, but that is not the case here.)

Docker containers are instances of Docker images that only exist while they are running — they are "ephemeral". Any data created within a Docker container is lost when the container is stopped. This means that once you stop the Surfmeter container, you will lose any registration information in the software, or any changes made to the measurement configuration.

One solution for this problem is to mount directories from your host machine into the container, so that data changes are made on your host system instead of inside the container. Once mapped to a host directory, data will persist across container restarts.

There are two ways to mount data to the host:

Bind mounts: mapping the data to a local directory.
Volumes: mapping the data to a Docker-specific special directory

What's the difference between bind mounts and volumes?

Bind MountsVolumes

Bind mounts have some drawbacks in terms of permissions. Firstly, they inherit the host file system's permissions, which can make it difficult to control the permissions for a container. Changes made to the host file system's permissions will be reflected in the bind mount, which can cause unintended consequences. Finally, it is not possible to specify custom user and group ownership for bind mounts, which can limit the flexibility in managing permissions for containers. We do recommend bind mounts for the configuration of the measurements, as bind mounts are easier to discover in the local filesystem compared to Docker volumes.

Docker volumes offer several benefits over bind mounts with respect to permissions. Host's permissions do not interfere with the volume's permissions. This reduces the risk of permissions-related issues caused by changes made to the host file system. We therefore recommend volumes for storing the profile/registration information.

Permissions for Bind Mounts¶

When you use bind mounts, you need to make sure that the user running the Docker container has the correct permissions to access the files in the bind mount. This is especially important on Linux, where the user ID inside the container is not necessarily the same as the user ID on the host system.

To work around this, you may need to change the permissions of the bind mount directory on the host system. For example, if you mount the config into the container, and you are running the container as user surfmeter with user ID 1001 (the default), you can change the permissions of the bind mount directory with:

sudo chown -R 1001:1001 ./config

This way the container itself can write files in the bind mount.

Running Surfmeter with Docker Compose¶

We provide a Docker Compose file that you can use to run Surfmeter.

Creating the Compose File¶

Pick any directory to place the Compose file.

First, create a file called docker-compose.yml containing the following:

name: surfmeter-lab-automator

services:
  surfmeter:
    image: registry.aveq.info/${CUSTOMER}/surfmeter-lab-automator:${CUSTOMER}-latest
    container_name: surfmeter
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - profile:/home/surfmeter/profile
      - ./reports:/home/surfmeter/reports
      - ./config:/home/surfmeter/config
      - ./logs:/home/surfmeter/logs
    env_file:
      - .env
    ports:
      - "127.0.0.1:5123:5123"
      - "127.0.0.1:8080:80"

volumes:
  profile:

Also create a file called .env next to the docker-compose.yml file:

CUSTOMER=yourcustomername

Replace the yourcustomername part with your customer ID. This will be sent to you. Contact us if you need help.

Starting the Container¶

To start the container, run:

docker compose up -d

This will start the container in detached mode (-d), so that it runs in the background.

Check that the container is running:

docker compose ps

This should print something like:

NAME        IMAGE                                                                     COMMAND                  SERVICE     CREATED        STATUS        PORTS
surfmeter   registry.aveq.info/<customer>/surfmeter-lab-automator:<customer>-latest   "/home/surfmeter/doc…"   surfmeter   1 minute ago   Up 1 minute   127.0.0.1:5123->5123/tcp, 127.0.0.1:8080->80/tcp

Great, you have successfully started the Surfmeter container!

You can now either continue with basic usage, or explore the rest of this page for more details on how to use Docker Compose.

Stopping the Container¶

You can stop the container with:

docker compose stop

To completely remove the container, use:

docker compose down

Updating the Container¶

To update the container, run:

docker compose pull
docker compose up -d

This will pull the latest version of the image from the registry, and restart the container.

Changing the Configuration¶

Have a look at our configuration documentation to learn how to override the default configuration.

Mounting Extra Directories¶

If you want to mount extra directories, you can do so by adding more bind mounts to the volumes part of Surfmeter service the docker-compose.yml file, just like for the config directory. This is useful for, e.g., storing reports, videos (screen recordings), or tcpdump traces from the container.

Interacting with the Container¶

Once the container is running in the background, you can execute Surfmeter commands in it. For example, to get the version:

BashWindows Batch (cmd)PowerShell

docker compose exec \
  --user surfmeter surfmeter \
  surfmeter-lab-automator/surfmeter-automator-headless \
  --version

docker compose exec ^
  --user surfmeter surfmeter ^
  surfmeter-lab-automator/surfmeter-automator-headless ^
  --version

docker compose exec `
  --user surfmeter surfmeter `
  surfmeter-lab-automator/surfmeter-automator-headless `
  --version

We'll cover basic usage in the following; this is just to make sure you can access the container. In particular, you will first need to register your container with the server, which is covered in the basic usage guide.

As for running studies, please consult the rest of this documentation.

Read on if you need more details on how to use Docker Compose.

Debugging inside the Container¶

You can drop into a shell in the container to execute arbitrary commands or troubleshoot things:

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

Exit the Docker shell with exit.

Exposed Ports (VNC and Health Check)¶

The container exposes ports 5123 and 8080. The former is used for the VNC server, and the latter for a basic health check API.

If the container cannot start due to a port conflict, you can change the ports in the docker-compose.yml file to something else that is available on your system.

VNC¶

To run the VNC server, exec into the container and run the run_vnc_server.sh script:

docker compose exec -it --user surfmeter surfmeter bash
cd surfmeter-lab-automator
./run_vnc_server.sh

You can then connect to localhost:5123 to access the VNC server, with a default password of surfmeter.

Tip

By default the ports are mapped to 127.0.0.1 (localhost) and cannot be accessed from outside the container. To expose them on all interfaces on the host machine, prefix the port with 0.0.0.0 in the docker-compose.yml file, i.e.:

ports:
  - "0.0.0.0:5123:5123"
  - "0.0.0.0:8080:80"

This will allow you to connect to the VNC server from any network interface on the host machine. Be aware that if you are not running a firewall, and your machine is directly connected to the internet, this will allow anyone on the internet to connect to your machine on these ports.

For more information see the FAQ entry.

Health Check¶

The port 8080 is used for a basic health check API. The API returns a 200 OK response with the following JSON body:

{
  "status": "green",
  "checks": { "xvfb": true, "freeMemory": true, "freeDiskSpace": true },
  "details": { "memoryPerProcess": { "python3": 10.66015625 } },
  "isRegistered": true
}

At the moment, it is sufficient to check that the API returns a response to verify that the container is running. We may add other checks in the future (e.g., status of running tests).

Now let's cover basic usage.