This document describes how to perform a docker installation of the Formant agent onto a target device.

Prerequisites

📘

Internet connectivity

The target device must have connectivity to app.formant.io and api.formant.io.

You can run the following script on your device terminal to output the robot's details and verify prerequisites:

bash <(wget -qO - https://app.formant.io/device-check.sh)

📘

Terminal Access

To install the Formant agent on the target device, you must have terminal access to the device and the ability to run commands.

Notes on Docker installations

📘

No automatic OTA updates

Docker installations of the Formant agent do not support OTA agent updates. Instead, all updates are done by updating the formant-agent docker image on robots.

Docker installation of the Formant agent

Step 1: Add device

Open the Formant sidebar using the top-left button. Select "Settings" ⇒ "Devices" ⇒ "Add device".

Step 2: Enter basic configuration for the device

A device is identified by a name. The name can be changed anytime but must be alphanumeric with characters a-z, A-Z, 0-9, dash (-), underscore (_), and dot (.).

Step 3: Install the Formant agent

📘

ROS users must set environment variables prior to installation

To install a ROS-compatible Formant agent, make sure to export the ROS_MASTER_URI environment variable prior to running the other terminal commands in this section (Step 3). For example, if your ROS master is at its default URI:

export ROS_MASTER_URI=http://localhost:11311

Setting this environment variable before installation is required for ROS-compatibility.

You can also export CATKIN_WS so the agent is able to ingest custom messages. For instance,

export CATKIN_WS=/home/ubuntu/catkin_ws

Configuring your catkin workspace path will allow Formant to ingest data using custom ROS message types.

If you do not use ROS, you do not have to export these environment variables.

Copy the installation command from the web application and paste it in the target device's terminal, but do not run it yet. Note the installation command contains of a provisioning token that is unique to the device and expires after 72 hours.

Change the script from install-agent.sh to install-agent-docker.sh. The modified command will now look like this:

bash <(wget -q0 - https://app.formant.io/install-agent-docker.sh) <YOUR PROVISIONING TOKEN>

Run the modified command to begin device installation.

Step 4: Verify successful installation

If the Formant agent has been installed and connection established, Formant will begin ingesting telemetry for default streams like CPU, Network, Memory, and Disk. Verify that these streams have live telemetry data in the device's telemetry page.

To navigate to a device's telemetry page, open the Formant sidebar using the top-left button, and click on the name of your device under the "Observe" tab.