Using MoveIt Studio in Docker

Note

This is an advanced usage document. To install the basic docker image, refer to Software Installation

Configure Docker

Manually Installing Docker on Ubuntu

The installation script linked in the Software Installation procedure will automatically install or update docker. However, for manual setups,

Follow this guide for installing Docker on Ubuntu.

Then, follow this guide to complete the post-installation step to allow running Docker as a non-root user.

MoveIt Studio Images

Use the following command to pull down specific versions of MoveIt Studio.

docker pull picknikciuser/moveit-studio:<TAG>

Where <TAG> can be replaced by any version of feature name available in our public Docker Image repo.

Using Docker Images

MoveIt Studio provides standard docker-compose.yaml and .env files for launching the default simulated environment using Docker Compose. The environment variables defined in .env can be modified to run different versions of MoveIt Studio, or with different robot configurations.

When testing a certain feature on robot hardware, it is useful to use pre-built Docker images based on the feature tag or branch.

Once you have determined the name (or <TAG>) of the image you want to use, you will need to set the STUDIO_DOCKER_TAG environment variable appropriately in .env file on both the agent PC and the realtime PC. For example STUDIO_DOCKER_TAG=1.7.0.

Next, pull down the latest version of this image on both machines (the agent PC and the realtime PC) by executing docker compose pull.

A brief summary on some of the key environment variables defined in .env:

STUDIO_CONFIG_PACKAGE

The name of the robot site configuration to launch.

STUDIO_HOST_CONFIG_DIR

This environment variable sets the path to a directory where modifiable configuration for MoveIt Studio (in particular, custom objectives, waypoints, etc) will be stored. This directory can be created by the install script, and must exist on the host machine before calling docker compose up.

STUDIO_HOST_DATA_DIR

This environment variable sets the path to a directory where the persistent data for MoveIt Studio will be stored. It is NOT recommended to modify the contents of this directory manually after installing MoveIt Studio - as doing so can break the installation on the host machine. This directory can be created by the install script, and must exist on the host machine before calling docker compose up.

STUDIO_HOST_USER_WORKSPACE

This environment variable sets the path to a directory where user-defined packages (site config, custom Behaviors, etc.) can be added. By default, the MoveIt Studio application will mount and build this workspace with colcon when starting up. This directory must be the root of a Colcon workspace containing your packages, and must exist on the host machine before calling docker compose up.

CYCLONEDDS_NETWORK_INTERFACE

The name of the network interface with which the host machine uses to communication with DDS peers. Can be determined using ip a or the like, e.g. CYCLONEDDS_NETWORK_INTERFACE=eno1

CYCLONEDDS_PEER_ADDRESSES

This environment variable should contain the IP addresses for all peer machines. For example, to run MoveIt Studio with the drivers on a realtime PC, and the agent/application on another, non-realtime PC, these might be set to 192.168.10.10 and 192.168.10.12 respectively. So, you would set CYCLONEDDS_PEER_ADDRESSES=192.168.10.10,192.168.10.12 on both machines.

Running MoveIt Studio

After setting the appropriate environment variables, you can run MoveIt Studio using Docker Compose. The provided docker-compose.yaml file specifies a number of services that can be executed across any machines in your DDS peer network. However, in the simplest case the entire application can be run with:

  • docker compose up

Setups that may have drivers or different services running on separate machines require specifying which services to launch. As mentioned above, we sometimes run non-realtime applications on an “agent PC” and drivers on a realtime PC. In this setup, both the docker-compose.yaml and the .env files should be copied to both machines, and the docker compose up command above should specify starting specific services on each machine:

  • On the realtime PC running the drivers:

    docker compose up drivers

  • On the non-realtime PC running the remainder of the applications:

    docker compose up agent bridge rest_api frontend_agent web_ui

Once the application has started, open a web browser on the machine running the web_ui service and navigate to http://localhost.

Running Graphical Programs in Docker Containers

The standard docker-compose.yaml sets the necessary bind mounts and environment variables to allow the user to run graphical programs from within the docker container.