Deep dive

From remote debugging to data discovery, learn how Formant works from top to bottom.

    Install agent in docker container

    The Formant agent can be set up in a docker environment in one of two ways: as a standalone container or as part of/inside a docker build. Please note the following about docker based deployment:

    1. It does not support OTA agent updates. Hence, you will have to update the agent manually whenever applicable
    2. It does not currently support video encoding on Nvidia Jetson platforms. Hence, we highly recommend using the Debian based installation if you are on Jetson based platform. 

    Installing as standalone container

    Prerequisite

    Make sure you have Docker installed.

    Step 1: Add device

    If this is the first device, you will be prompted to add device from the signup screen. If not, add device as follows:

    From the burger menu  select Settings⇒ Devices ⇒ Add device

    Step 2: Enter name for 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 (.).

    Click on advanced settings to enable/disable SSH, add tags to the device or apply configuration templates already available within the org. If you choose auto-configure, Formant will choose a set of streams and configure/ display a certain way. 

    Step 3: Install the docker container of Formant agent 

    Warning

    If you are running ROS, make sure that ROS_MASTER is set your environment variable. This is how Formant detects that it is a ROS based device and pulls the appropriate packages.  

    export ROS_MASTER_URI=http://localhost:11311

    Copy the installation command from the web application and paste it on the device/robot's terminal. The installation command consists of a provisioning token that is unique to the device and expires after 72 hours. If you are unable to install the device within that timeframe, please refresh your token by using the reprovisioning flow

    If you want to install a standalone Docker container of Formant agent, use the following command. Please note the following about docker based deployment:

    1. It does not support OTA agent updates. Hence, you will have to update the agent manually whenever applicable
    2. It does not currently support video encoding on Nvidia Jetson platforms. Hence, we highly recommend using the Debian based installation if you are on Jetson based platform. 
    bash <(wget -qO - https://app.formant.io/install-agent-docker.sh) <YOUR PROVISIONING TOKEN>

    Running into installation issues?

    Check out our agent installation FAQ to see if it helps. Else, contact us support@formant.io


    Step 4: Configure your agent

    An agent’s configuration specifies what data it should ingest from your application, how it should buffer that data, what metadata (tags) it should apply, and other options. Any changes to the agent’s configuration are versioned, saved to the cloud, and synchronized to the agent the next time it has internet access. You can see the agent’s active and desired configuration versions at any time at the device settings page.

    If you chose auto-configure from the installation menu, Formant will automatically choose set of streams and configure it for you. Visit our help page on configuring the agent for more details.

    Notes

    Image Repository

    The full list of available images can be found on Docker Hub.

    Our container images have support for AMD64, ARM64, and ARM. We provide both ROS Melodic and ROS Kinetic variants as well.

    ROS

    We have included a ROS-based docker-compose as well. This will start up two containers, one running a ROS Master and our Agent. You should note the formant.env file contains the ROS_MASTER_URI pointed to the container over the formant docker network.

    Container State

    The agent uses a docker volume to store state and persistent data. If the volume is deleted you will need to reprovision the agent.

    The provisioning token you use to initialize the agent is a one-time use token. You can remove it from the formant.env file after the credentialing process is done.

    MacOS

    Docker for Mac users may need to set FORMANT_AGENT_IP=0.0.0.0 in the formant.env file in order to access the local gRPC and HTTP interfaces from their host machine. This is to ensure that the Formant agent is reachable from outside its container networking namespace.

    Installing into your docker build

    The agent installation inside of a docker build is quite similar to a regular Debian installation with a few key differences. 

    • First, we will not have an interactive GUI so we will need to turn off any user prompts. 
    • Second, we will not be provisioning the agent during the build but at runtime.

    First, let's set up some RUN commands to get the Formant Debian repo setup. (Note: you can eventually add this to a install-formant-agent.sh script and run as one command). It is also assumed this is run as the root user during the build.

    RUN apt-key adv --fetch-keys https://keys.formant.io/formant.pub.gpg
    RUN echo "deb https://repo.formant.io/formant/debian <VERSION_CODENAME> main" | tee -a /etc/apt/sources.list > /dev/null

    These directives setup the Formant repository. Make sure to replace <VERSION_CODENAME> with your Linux distro (xenial bionic jessie stretch buster).

    Next set the service_enable debconf parameter to false. This ensures the normal interactive Debian workflow:

    RUN echo formant-agent formant-agent/service_enable boolean "false" | debconf-set-selections

    Next, run the install directives for the agent:

    RUN apt update && DEBIAN_FRONTEND=noninteractive apt install -y formant-agent --no-install-recommends

    The last step is to startup the agent when your container starts. If you are using the entrypoint directive with a shell script you can add:

    /usr/lib/formant/formant-agent &

    You can send the agent logs to /dev/null as well to not interfere with your application's output:

    /usr/lib/formant/formant-agent > /dev/null 2>&1 &

    To it to run the agent as a forked process.

    Many of the debconf parameters the agent takes during normal installation are also exposed as environment variables. You can set these as you would any other docker environment variables. For ROS users, make sure to set ROS_MASTER_URI and CATKIN_WS to ensure the agent picks up the ROS runtime and your custom ROS messages.

    To provision the agent, make sure that you set the FORMANT_PROVISIONING_TOKEN in the environment. The token is one-time use so it is safe to keen in your environment or .env file. A full example of installing the agent into a container is available here

    © 2020 Formant • 1999 Bryant St · San Francisco, CA 94110