Skip to content

Registration

Each instance of the Automator needs to be registered with the Surfmeter server. For this, you need a registration key from us.

Automatic Registration with Docker

If you are using Docker Compose and have configured the SURFMETER_AUTO_REGISTER and SURFMETER_DEFAULT_REGISTRATION_KEY environment variables in your docker-compose.yml file (as shown in the Docker setup guide), your container will register automatically on first startup. You do not need to run the manual registration command below.

You can verify successful registration by checking the container logs or the health check API. Skip to the labeling or tagging sections if you need to modify client metadata after automatic registration.

Manual Registration

Register the software with the register command. You must specify the key via the --registrationKey option:

./surfmeter-automator-headless register \
    --registrationKey <registrationKey> \
    --label <label>

Don't delete the profile directory

Registering the extension creates a directory called profile next to the other directories (i.e., as a sibling of the surfmeter-lab-automator directory). It contains the Google Chrome user profile that stores the login. Please do not delete this directory, as it will cause the registration to become invalid.

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless register \
    --registrationKey <registrationKey>

Here, replace <registrationKey> with the actual registration key, and <label> with the unique label you want to use to identify the client later in our dashboards. The label is optional, but it is recommended to set it nonetheless.

If the command was successful, it will print a log, showing the following lines at the end, containing “Registered client with UUID”:

{"level":30,"time":"2023-02-11T13:29:35.792Z","pid":65,"hostname":"4d3931b9c534","msg":"Registered client with UUID 4c8e6168-291d-4b76-b993-5a8673371616"}

Optional: Storing a Registration Key in a Configuration File

If you have been given an automatorConfig.json configuration file, and if that configuration file contains a registrationKey field, registering the extension is possible automatically via the register command.

./surfmeter-automator-headless register

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless register

This makes it possible to distribute the software without having to pass the registration key on the command line every time.

Labeling Clients

As we indicated above, you can additionally pass a label during registration so that any measurements made with the client can be uniquely identified later:

./surfmeter-automator-headless register \
    --registrationKey <registrationKey> \
    --label TestClient123

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless register \
    --registrationKey <registrationKey> \
    --label TestClient123

The label will be part of each measurement data point, and can be used to filter the data later.

To change the label later, use the setLabel command:

./surfmeter-automator-headless setLabel \
    --label TestClient123

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless setLabel \
    --label TestClient123

Tagging Clients

Furthermore, you can tag clients in a similar way. Each client can have multiple tags, and each tag can be assigned to multiple clients.

./surfmeter-automator-headless register \
    --registrationKey <registrationKey> \
    --tags tag1 --tags tag2

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless register \
    --registrationKey <registrationKey> \
    --tags tag1 --tags tag2

Note that each tag is passed as a separate --tags option.

Similarly to labels, tags will be part of each measurement data point, and can be used to filter the data later.

To set tags later, use the setTags command:

./surfmeter-automator-headless setTags \
    --tags tag1 --tags tag2

docker exec --user surfmeter -it surfmeter surfmeter-lab-automator/surfmeter-automator-headless setTags \
    --tags tag1 --tags tag2

Unregistering Clients

You can use the unregister command to unregister a client. This will:

  • Return the license to the license pool on the server
  • Delete the profile directory
  • Delete the cache file

The client will not be able to run any studies anymore.

Once you are done, you can run a study.