Create Overlay Docker Images

When working with MoveIt Studio, you will likely create new packages which may contain:

New Behaviors and Objectives
Base and site configs
Descriptions and drivers for a new robot
Novel algorithms currently not present in MoveIt Studio

For many of these applications, you can mount a user workspace directly into the MoveIt Studio Docker containers. However, there may be some use cases where this may not be sufficient, such as:

Your workspace requires additional binary packages, where rosdep install, apt-get install, etc. is needed to build the workspace.
The hardware and/or algorithms you are working with require additional dependencies.
You want to install additional tools for debugging during development.

In this document, we will use the custom MoveIt Studio workspace defined in the moveit_studio_ws repository as our example.

Note

The actual Dockerfile and docker-compose-overlay.yaml files in the moveit_studio_ws repository are more complicated, but this tutorial goes through a minimal example for clarity.

Creating a Release Overlay Container

Let us extend the 2.0.0 release of MoveIt Studio with some workspace defined in our folder ~/moveit_studio/moveit_studio_ws/.

First, go to your ~/moveit_studio/moveit_studio_ws folder and create a Dockerfile.overlay file:

# Extend the 2.0.0 release of MoveIt Studio
FROM picknikciuser/moveit-studio:2.0.0 as moveit-studio-custom-release

# Copy the src/ folder of the workspace into the image
ENV MOVEIT_STUDIO_CUSTOM_WS=/opt/custom_ws
COPY ./src $MOVEIT_STUDIO_CUSTOM_WS/src
WORKDIR $MOVEIT_STUDIO_CUSTOM_WS

# Install dependencies and build the workspace
RUN . "${OVERLAY_WS}/install/setup.sh" && \
  apt-get update && \
  rosdep install -q -y --from-paths src --ignore src && \
  colcon build

Next, create a docker-compose-overlay.yaml file which extends the docker-compose.yaml file that was installed. We recommend creating a copy or symbolic link of this docker-compose.yaml file in your current folder.

version: "3.9"
services:
  base:
    extends:
      file: docker-compose.yaml
      service: base
    # Optionally allow building this service from source with `docker compose build`
    build:
      context: .
      dockerfile: Dockerfile.overlay
      target: moveit-studio-custom-release

  # Extend all the services from the base image
  agent:
    extends:
      file: docker-compose.yaml
      service: agent
  bridge:
    extends:
      file: docker-compose.yaml
      service: bridge
  rest_api:
    extends:
      file: docker-compose.yaml
      service: rest_api
  drivers:
    extends:
      file: docker-compose.yaml
      service: drivers

Finally, you can create a .env.overlay file containing the necessary variables to use when launching MoveIt Studio. For this example, you can include the following contents.

STUDIO_CONFIG_PACKAGE=picknik_ur_site_config
STUDIO_DOCKER_TAG=2.0.0
STUDIO_LICENSE_KEY= # Place your license key here

Now, you should be able to build and launch your MoveIt Studio overlay release image:

docker compose -f docker-compose-overlay.yaml --env-file .env.overlay build
docker compose -f docker-compose-overlay.yaml --env-file .env.overlay up

Creating a Dev Container

With the release container workflow from the previous section, every time you change your source code you will need to rebuild the Docker image entirely for the changes to take effect when launching MoveIt Studio. One way to get around this is by making a developer container (or dev container) that mounts the source code and lets you build and run it repeatedly without restarting the container.

As an example, let us extend the moveit-studio-custom-release target in Dockerfile.overlay with a development target that adds a few extra packages for debugging. Additionally, we will add this file as an entrypoint that runs every time the container is entered. This file adds some useful aliases, sources the workspace every time the container is entered, and configures DDS settings for ROS 2 inter-process communication.

FROM moveit-studio-custom-release as moveit-studio-custom-dev

# The location of the user's workspace inside the container
ENV MOVEIT_STUDIO_CUSTOM_WS /opt/custom_ws
WORKDIR $MOVEIT_STUDIO_CUSTOM_WS

# Install any additional packages for development work
# hadolint ignore=DL3008
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    less \
    gdb \
    ros-humble-rclcpp-dbgsym

# Add the developer entrypoint
COPY .docker/entrypoint-dev.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
# Source the entrypoint when starting shell sessions, and prevent non-zero exit codes from terminating the session
RUN echo "source /entrypoint.sh" >> ~/.bashrc && \
    echo "set +e" >> ~/.bashrc
CMD ["/usr/bin/bash"]

You can then extend the docker-compose-overlay.yaml file with a new service named dev as follows:

dev:
  extends: base
  build:
    target: moveit-studio-custom-dev
  # This image deliberately has no user prefix because it should not be pushed!
  stdin_open: true
  tty: true
  privileged: true
  volumes:
    - ${HOME}/.ros/log_moveit_studio:/root/.ros/log:/root/.ros/log
    # Mount source code
    - ./src/:/opt/custom_ws/src/:rw
    # Mount anonymous volumes to build cache and artifacts
    - /opt/custom_ws/build
    - /opt/custom_ws/install
    - /opt/custom_ws/log
    # Allow access to host hardware e.g. RealSense cameras
    - /dev:/dev
  command: sleep infinity
  # Making a separate profile prevents this service from being built when using `docker compose build`
  profiles: ["dev"]

Now, you should be able to build and launch your MoveIt Studio overlay dev container:

docker compose -f docker-compose-overlay.yaml --env-file .env.overlay build dev
docker compose -f docker-compose-overlay.yaml --env-file .env.overlay up dev

Once you have started the dev container, you can enter an interactive Bash session and launch one of the MoveIt Studio launch files directly. For example:

docker compose -f docker-compose-overlay.yaml --env-file .env.overlay exec -it bash
colcon build
source install/setup.bash

Once inside the container, you can compile, run tests, or even launch different parts of the MoveIt Studio applications. Because the entrypoint runs source /common_aliases.sh, the following shortcuts are available to launch different applications inside the container:

agent.app             # brings up the MoveIt Studio agent
robot.app             # brings up robot drivers (if relevant)
studio_bridge.app     # brings up MoveIt Studio bridge
rest_api.app          # brings up MoveIt Studio REST API
formant-agent         # brings up Formant (aka the frontend) agent

Note

Using Docker containers for development is a common practice. Many IDEs, such as Visual Studio Code and PyCharm <https://www.jetbrains.com/help/pycharm/using-docker-as-a-remote-interpreter.html>, have built-in support for developing with Docker containers. Once you have familiarized yourself with the steps above, we recommend setting up your favorite IDE(s) to help you develop new functionality for MoveIt Studio.