Using Docker

The Transitive agent and capabilities can be installed in a Docker container. Please follow the instructions below or use our example docker image.

Build

Include this snippet in your Dockerfile:

ARG BASE_IMAGE
FROM ${BASE_IMAGE:-'ubuntu:20.04'}

RUN apt-get update
RUN apt-get install -y build-essential curl git lsb-release gnupg

# Fill in id and token from the curl command on your fleet page.
RUN curl -sf "https://install.transitiverobotics.com?id=...&token=....&docker=true" | bash

# Optionally: add a custom configuration file
WORKDIR /transitive-preinstalled
COPY config.json .

# Optionally: set some env vars, e.g., ROS_DOMAIN_ID, ROS_IP, etc.
COPY .env_user .

WORKDIR /root
COPY entrypoint.sh .
CMD ["./entrypoint.sh"]

The script run by the curl command will install the agent and detect the docker build environment, so it won't start the agent right away. Instead it will check the config.json file, if one was provided, and pre-install any specified desiredPackages. See Configuration for an example.

Edit your entrypoint or CMD script to include:

if [ ! -e $HOME/.transitive/.installation_complete ]; then
  cp -r /transitive-preinstalled/. $HOME/.transitive
  rm -rf /transitive-preinstalled
fi;
cd $HOME/.transitive
bash start_agent.sh

Note: the . at the end of the source in the cp command is important.

Make sure your entrypoint.sh is executable (chmod +x entrypoint.sh).

Run

• Since Transitive uses linux namespaces to sandbox capabilities, you need to run your container with --privileged. Using --security-opt seccomp=unconfined might work, too.
• Inside your container, $HOME/.transitive needs to be a bind-mounted folder from your host. For instance, run mkdir $HOME/transitive-docker and run your container with -v $HOME/transitive-docker:/root/.transitive, if running as root inside your container.
  • This is required for two reasons:
    • to give Transitive a place where it can permanently store files, and
    • to allow usage of this folder for creating an overlayfs mount onto /usr inside the container.
• Make sure, /etc/machine-id is not empty, e.g., run hostname > /etc/machine-id as part of your entry point. The ID you set needs to be unique for each robot in your fleet. Usually the file is written by systemd on first boot using a randomly generated id that is long enough to assume it is globally unique. But since docker images are, of coruse, usually shared between devices, this uniqueness guarantee may not exist, or the file may be empty completely if systemd is not used in the container.
  • Alternatively you can set the TR_INSTALL_HASH environment variable to an ID of your own choosing in the docker run command.

Example

docker run --privileged -v $HOME/.transitive:/root/.transitive -e TR_INSTALL_HASH=bot123 TAGNAME