Install and Set Up Docker for ROS, ROS 2, and Gazebo

R2026b

This page provides installation instructions for Docker and guides you through building a Docker image from the Dockerfile included in the Docker and Support Files for ROS Toolbox repository, which is provided as a supplement to ROS Toolbox. The Docker image comes preinstalled with Gazebo and ROS, enabling MATLAB^® and Simulink^® to seamlessly integrate with the Gazebo robot simulator and an external ROS (Robot Operating System). Once you build the Docker image following the given instructions in this page, you can create instances of Docker container to run the relevant examples in ROS Toolbox.

Built on Ubuntu^® 24.04 Noble, this Docker image works on multiple platforms, including Windows^®, Linux^®, and Mac.

This graphic image below is a sample demonstration of connectivity between local host machine and remote device running the Docker container.

Prerequisites

This requires MATLAB R2025a or higher.

Dockerfiles Shipped with ROS Toolbox

The ROS Toolbox provides three Dockerfiles for ROS 2 listed in this table below.

Name	Path	Content
base	ros_jazzy/Ubuntu/base	ROS 2 Jazzy desktop installation
gazebo	ros_jazzy/Ubuntu/gazebo	ROS 2 Jazzy desktop installation Gazebo Harmonic robot simulator
PX4	ros_jazzy/Ubuntu/px4_gazebo	ROS 2 Jazzy desktop installation Gazebo Harmonic robot simulator PX4 Autopilot v1.14

Select the 'base' image for running ROS 2 examples that involve only code generation. Use the 'gazebo' image for examples requiring a Gazebo world, and choose the 'PX4' image for examples that involve both PX4^® and Gazebo.

Additionally, the ROS Toolbox provides two Dockerfiles for ROS listed below.

Name	Path	Content
ubuntu	ros_jazzy/Ubuntu	ROS Noetic desktop installation Gazebo Classic 11.0.0
debian	ros_jazzy/Debian

Instructions for Platform-Based Docker Installation

Windows (WSL)

1. To install and set up WSL 2 on your machine, refer to the steps provided in this Install WSL for Docker documentation.

2. Open WSL Terminal and install Docker Engine using the steps provided in this repository.

3. Once you install Docker Engine, refer to the post installation steps provided in the Manage Docker as Non-Root User documentation.

Linux (Ubuntu)

1. To install and set up Docker on Linux (Ubuntu), refer to the steps provided in the Docker for Linux documentation.

2. Once you install Docker Engine, refer to the post installation steps provided in the Manage Docker as Non-Root User documentation.

Mac

To install and set up Docker on Mac, refer to the steps provided in the Docker for Mac documentation.

Setup Instructions post Docker Installation

Set Up Docker Shipped with ROS Toolbox

1. To download Docker for ROS and ROS 2, and the corresponding support files, navigate to the Docker and Support Files for ROS Toolbox GitHub^® repository.

2. Select a branch compatible with your installed MATLAB release and run this command in the WSL/Linux/Mac terminal to clone the repository:

   git clone --branch <branch-name> https://github.com/mathworks-robotics/Support-and-Docker-Files-for-ROS-Toolbox.git

   This creates a folder 'Support-and-Docker-Files-for-ROS-Toolbox' with a structure such as the one shown in this reference image below:

   

3. Run this command to navigate to the 'Support-and-Docker-Files-for-ROS-Toolbox' folder:

   cd Support-and-Docker-Files-for-ROS-Toolbox

4. After navigating to the 'Support-and-Docker-Files-for-ROS-Toolbox' folder, select the suitable Dockerfile as per your requirement, find the path to the corresponding Dockerfile from the tables in the Dockerfiles Shipped with ROS Toolbox section, and run this command to build the image:

   docker build -t <image-name> <path-to-dockerfile>

   For example, you can use this command below to build the Dockerfile for ROS 2 Jazzy with Gazebo simulator:

   docker build -t mw_ros_jazzy ros_jazzy/Ubuntu/gazebo

Once you build the Docker image, you can create instances of Docker container to run the corresponding ROS and ROS 2 examples that use Docker.

Set Up Externally Sourced Docker

If you have a custom Docker image on your host machine that includes supported versions of ROS or ROS 2, follow the instructions below to install the necessary dependencies for ROS Toolbox examples and build a new image without modifying the original one. This workflow assumes that your existing Docker image supports either ROS or ROS 2, depending on the example.

1. To download Docker for ROS and ROS 2, and the corresponding support files, navigate to the Docker and Support Files for ROS Toolbox GitHub repository.

2. Pick a branch compatible with your installed MATLAB release and run this command in your host machine’s terminal to clone the repository:

   git clone --branch <branch-name> https://github.com/mathworks-robotics/Support-and-Docker-Files-for-ROS-Toolbox.git

   This creates a folder 'Support-and-Docker-Files-for-ROS-Toolbox' with a structure such as the one shown in this reference image below:

3. Run this command to navigate to the 'Support-and-Docker-Files-for-ROS-Toolbox' folder:

   cd support-and-docker-files-for-ros-toolbox/ros_<distro>/<platform>

4. After navigating to the 'Support-and-Docker-Files-for-ROS-Toolbox' folder, edit the Dockerfile to replace FROM osrf/ros:jazzy-desktop with FROM <your-image-name> to configure your custom Docker image to run ROS Toolbox examples.

5. Run this command to build the image:

   docker build -t <image-name> <path-to-edited-dockerfile>

Once you build the Docker image, you can create instances of Docker container to run the corresponding ROS and ROS 2 examples that use Docker.

Run Docker Container

Note

This step is NOT relevant for running ROS Toolbox examples.

Run this command to set up Docker and test its deployment. It supports remote code generation workflow.

docker run -it --net=host --name <container-name> <image-name>

The preconfigured Docker shipped with ROS Toolbox also comes with the capability of displaying GUI applications. You can see the following instructions to display the GUI applications using VNX or Xserver.

View GUI Application Using VNC

Use these instructions to set up Docker for running ROS or ROS 2 examples using VNC.

1. Run a container from the built image.

   docker run -it --net=host --name <container-name> <image-name>

2. Open another terminal and run this command below.

   docker exec -it <container-name> bash

3. Run the commands to open Gazebo.

   source /home/user/ros2_ws/install/setup.bash
   ros2 launch turtlebot3_gazebo empty_world.launch.py

View GUI Application Using Xserver

Use these instructions to set up Docker for running ROS or ROS 2 examples using Xserver.

1. Run this command in terminal to allow connections from docker:

   xhost +local:docker

2. Now, use this command to run a container from the built image:

   docker run -it --env="DISPLAY=$DISPLAY" --env="QT_X11_NO_MITSHM=1" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" --device /dev/snd --net=host <name_of_image> bash

3. Once inside the container, run these commands to open Gazebo.

   source /home/user/ros2_ws/install/setup.bash
   ros2 launch turtlebot3_gazebo empty_world.launch.py