Install the Formant agent via Docker
This guide will teach you how to install the Formant agent to your device via Docker.
Docker installations of the Formant agent do not support automatic, over-the-air (OTA) agent updates.
To update the Formant agent, you will have to update the
formant-agent
Docker image on your device.
Prerequisites
System requirements
The Formant agent is an extremely lightweight tool which sets up data pipelines on your device. The base footprint of the agent itself on a device is minimal. Depending on your application, you can configure the agent and your device to store and transfer large amounts of data (e.g., video cache and streaming), which will require greater memory and CPU capability.
Supported target operating systems |
---|
Ubuntu 22.04 ("Jammy") |
Ubuntu 20.04 ("Focal") |
Ubuntu 18.04 ("Bionic") |
Debian 11 ("Bullseye") |
Debian 10 ("Buster") |
Debian 9 ("Stretch") |
Supported architectures |
---|
amd64 |
arm64 |
Install Docker to your device
You'll need to have Docker installed to your device to install the Formant agent.
Create a device
Follow the instructions in Create a device to add a new device to your Formant organization.
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.
Step 1 (ROS only): Set environment variables
Setting this environment variable before installation is required for ROS compatibility.
To install a ROS-compatible Formant agent, make sure to export the ROS_MASTER_URI
environment variable first. For example, if your ROS master is at its default URI:
export ROS_MASTER_URI=http://localhost:11311
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.
Ensure the ROS master is running
The Formant agent needs to communicate with the ROS master running on your device in order to properly ingest ROS data.
You can check that the ROS master is running by using a command like
rostopic list
.
Step 2: Install the Formant agent
Following from the instructions in Step 2 of Create a device: you will see a command which installs the Formant agent to your device.
- 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
toinstall-agent-docker.sh
. The modified command will now look like this:
bash <(wget -qO - https://app.formant.io/install-agent-docker.sh) <YOUR PROVISIONING TOKEN>
You can add optional arguments to the Docker run command by using the
--args
flag at the end of the modified command. An example may be to set a custom DNS server for the container, which is done using the--dns
flag. This would look as follows:bash <(wget -qO - https://app.formant.io/install-agent-docker.sh) <YOUR PROVISIONING TOKEN> --args "-dns=192.168.1.100"
- Run the modified command to begin device installation.
Step 3: 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.
- In Formant, in the upper-left corner, open the menu. Under the Observe tab, click on the name of your device.
- Verify that these streams have live telemetry data in the device's telemetry page.
Managing a Docker installation
Updating the Formant agent
To update the agent, re-run the convenience script without a provisioning token:
bash <(wget -qO - https://app.formant.io/install-agent-docker.sh)
Enabling and disabling the agent running on startup
By default, after installation, the agent runs on startup.
To set the agent to run on startup:
docker update --restart=yes formant-agent
To disable the agent from running on startup:
docker update --restart=no formant-agent
Starting and stopping the agent
By default, the agent will be enabled and run on startup.
To start the agent:
docker start formant-agent
To stop the agent:
docker stop formant-agent
To restart the agent:
docker restart formant-agent
Retrieving agent logs
docker logs -f formant-agent
Uninstalling the Formant agent
This command stops any running formant-agent
containers and removes the formant-agent
image:
docker rm -f formant-agent
To remove the agent credentials as well, run:
rm -rf /var/lib/formant
See also
- Install the Formant agent
- Environment variables for the agent
- Troubleshooting an agent installation
- Error invoking Docker in Formant terminal
If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].
Updated about 2 months ago