How to use Husarion Docker images

Docker Compose enables the simultaneous launch of multiple containers with specific configurations. It is the recommended method for using Docker images. Compose files (compose.yaml) describe the configurations of the containers to be started. For basic use you can use our cheat sheet detailed guidance on using Docker and Docker Compose, please consult the official Docker documentation.

How to use Docker

By following these steps, you can take advantage of Docker's capabilities to seamlessly deploy and run Husarion robot software.

Basic Containers Management

To learn basic commands from a Docker CLI, let's assume that we have created the following compose.yaml file in a current directory, with the following content:

compose.yaml

services:

  rosbot-xl:
    image: husarion/rosbot-xl:humble
    command: ros2 launch rosbot_xl_bringup bringup.launch.py mecanum:=${MECANUM:-True}

  microros:
    image: husarion/micro-ros-agent:humble
    ports:
      - 8888:8888/udp
    command: ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888

Run the following commands from the directory with compose.yaml:

Starting Docker containers

# start all containers
docker compose up
# start only the "microros" container
docker compose up microros
# start all containers (detached mode)
docker compose up -d
# start only the "microros" container (detached mode)
docker compose up -d microros

Listing containers

# List running containers
docker ps
# List all containers (including stopped)
docker ps -a

Stopping containers

# stop all containers
docker compose down
# stop only a single container
docker compose down rosbot-xl

Remove a container

# remove a single container ()
docker container rm <CONTAINER_ID>
# remove all stopped containers
docker container prune

Remove all unused: containers, networks, images

docker system prune

Updating Containers

Docker images are frequently updated to improve performance, add new functionalities or fix existing bugs. To update an existing image follow the below steps:

1. Stop all running containers.

docker stop $(docker ps -q)

2. Remove all created containers.

docker container prune

3. Pull a new Docker image.

docker pull <image>
# eg.
docker pull husarion/panther:noetic

After the pull process finishes, the Docker image is ready to use.

Configuring containers

Restart

The behavior of existing containers after they exit can be controlled using compose parameter called restart. Possible options are:

• no - the container doesn’t restart under any circumstance,
• always - the container always restarts,
• on-failure - the container restarts if the exit code indicates an on-failure error,
• unless-stopped - the container always restarts unless it was stopped arbitrarily, or by the Docker daemon.

note

For Husrion's robots in most cases unless-stopped configuration is used. This means Docker containers will be automatically restarted after the robot is turned off and on again.

NVIDIA acceleration

If you have NVIDIA GPU you can install NVIDIA Container Toolkit and add following configuration.

    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    runtime: nvidia

• runtime: nvidia (required) enables the use of NVIDIA GPUs
• CUDA_VISIBLE_DEVICES (optional) is used to control the visibility of GPUs
• NVIDIA_DRIVER_CAPABILITIES (optional) is used to list of capability flags that represent different driver features (e.g. NVIDIA_DRIVER_CAPABILITIES=compute,graphic,utility to enable CUDA computations, graphic and utility functions).

Examples

ROSbot 2R (Gazebo) + Rviz2 + SLAM + Nav2

The purpose of the example is to demonstrate the setup of a Docker Compose file that allows running a simulation of ROSbot 2R with Rviz2, SLAM and Nav2 on ROS 2 Humble distribution. The goal is to showcase how different components can be combined and orchestrated using Docker Compose to create a cohesive and integrated environment for ROS-based robotics simulations.

First what you need to do is finding appropriate images to run.

1. To run the simulation of ROSbot 2R in Gazebo, go to Robots Docker Images table where you find the image - husarion/rosbot-gazebo with the tag humble.
2. To run SLAM and Nav2, go to Autonomy Docker image table where you will find the images: husarion/navigation2 and husarion/slam-toolbox with the mark humble.
3. To run Rviz2, go to Tools Docker Images table where you find the image husarion/rviz2 with tag humble

Let's combine all this information into a compose.yaml file.

services:

  rosbot_simulation:
    image: husarion/rosbot-gazebo:humble
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
    environment:
      - DISPLAY=${DISPLAY:?err}
    command: >
      ros2 launch rosbot_gazebo simulation.launch.py

  slam:
    image: husarion/slam-toolbox:humble
    command: >
      ros2 launch slam_toolbox online_sync_launch.py
        slam_params_file:=/slam_params/rosbot2.yaml
        use_sim_time:=True

  navigation:
    image: husarion/navigation2:humble
    command: >
      ros2 launch nav2_bringup navigation_launch.py params_file:=/nav2_params/rosbot2_navigation.yaml
        use_sim_time:=True

  rviz2:
    image: husarion/rviz2:humble
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
    environment:
      - DISPLAY=${DISPLAY:?err}
    command: ros2 run rviz2 rviz2 -d /settings/rosbot2-nav2-demo.rviz

NVIDIA acceleration

If you have NVIDIA GPU you can accelerate computation by adding few lines. Click here to find out.

To launch the example create a compose.yaml file on your computer and run:

xhost +
docker compose up

As a result of running the above compose.yml, a simulation of RObot 2R is launched with autonomy enabling navigation and mapping of the environment. You should get a result similar to the following.