In this simple guide, I will explain how to create, use, and work efficiently with ROS + Docker.

The primary audience for this article is the students of the Master’s program in Robotics and Artificial Intelligence at the University of León, but it can also be useful for anyone looking to work with ROS/ROS 2 and Docker.

The goal is to leverage the advantages of Docker to create different ROS images for isolated environments, so you don’t have different versions of ROS installed on your system and lots of commands to memorize to switch from one version to another. Something like the Conda of ROS.

To sum up:

  1. Install Docker
  2. Create Docker images with ROS + VNC
  3. Set up the VSCode server for each image

Install Docker

The easiest way is to install Docker Desktop. This instructions are for Ubuntu based machines.

Go to https://docs.docker.com/desktop/install/ubuntu/ and follow the instructions:

Uninstall docker-desktop if you had it:

sudo apt remove docker-desktop

Remove any related files:

rm -r $HOME/.docker/desktop
sudo rm /usr/local/bin/com.docker.cli
sudo apt purge docker-desktop

Add Docker’s software repository (it may chage overtime):

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Download the latest .deb package (the link varies by date, so look it up)

And install it by double-clicking on the .deb. If double-clicking doesn’t work and the eddy program doesn’t open, you can install it like this:

sudo apt install <file.deb>

It is assumed that by installing this, the terminal docker is also installed, which is great. Now a few recommended configurations. To avoid being asked for sudo every time you enter a docker command:

sudo usermod -aG docker $USER

To verify that everything works well:

docker run hello-world

To start docker-desktop, look for it among the installed applications.

To update it, download the latest debian package again and install it the same way.

Docker desktop is just an interface to manage the docker containers you have on the system but with buttons and such, instead of doing everything by console. It’s more comfortable than by console although in this tutorial I use it more often.

Start ROS Images

To start the ROS images, we will use the images from https://hub.docker.com/r/tiryoh/ros-desktop-vnc

These images start an Ubuntu docker container, with a user interface that we can see from the browser, with all the hassle of installing ROS already done. A delight.

The guy who makes these images (tiryoh) has different versions available, so switching between versions shouldn’t be harder than opening another machine with a command.

To start the ROS1 virtualization:

docker run -d -p 6080:80 -e RESOLUTION=1600x900 --shm-size=512m --name ros_noetic_vnc tiryoh/ros-desktop-vnc:noetic

To start the ROS2 virtualization:

docker run -d -p 6080:80 -e RESOLUTION=1600x900 --shm-size=512m --name ros_humble_vnc tiryoh/ros2-desktop-vnc:humble

Important aspects of this command:

  • -p 6080:80 this maps the internal port of the machine (80) to the port where we will see the VNC connection (6080, we connect to the virtual desktop at https://localhost:6080). If we have several machines running at the same time, it will give us an error if we have the same port in the second place, and we will have to change it and remember which port it is. Anyway, if we use docker desktop, within the containers section it will already show us which port each container has, and even if we click it opens the browser.

  • -e RESOLUTION=1600x900 this resolution is fine to see the virtual desktop on a browser screen. If for some reason you have a 4k screen and it looks very small with this resolution, you can change it here.

  • --name ros_noetic_vnc this is where you name the container. I think having one per subject is fine, so it could be ros_noetic_vnc_middleware

  • tiryoh/ros-desktop-vnc:noetic is the name of the image, like a GitHub repo. The first is the author, the second is the image, and the third is like the branch. This is where we change the ROS version.

For ROS1:

  • tiryoh/ros-desktop-vnc:noetic -> ROS noetic (recommended)
  • tiryoh/ros-desktop-vnc:melodic -> ROS melodic (the previous one)
  • tiryoh/ros-desktop-vnc:kinetic -> ROS kinetic (old)

For ROS2:

  • tiryoh/ros2-desktop-vnc:foxy -> ROS2 foxy
  • tiryoh/ros2-desktop-vnc:galactic -> ROS2 galactic
  • tiryoh/ros2-desktop-vnc:humble -> ROS2 humble

Once we have selected the version we want, we run the command, wait for everything to download and mount the image, and open the port we assigned in the browser (https://localhost:6080), or go to docker-desktop and click on the container’s port.

We should see a simple user interface, not the one we are used to seeing in Ubuntu, but another simpler one so it doesn’t take too much resources. We can open consoles, folders, etc. If we enter the ROS commands, we will see that they are installed by default, etc.

We now have our virtual ROS system running. Now we just need to find a way to write code and upload files without dying in the attempt. For that, we will use a VSCode server that will connect to our virtual container.

NOTE: this is for the first time you start one of these containers. The rest of the times, you can open docker-desktop and go to the containers section, and press the play symbol to start the container.

Set up the VSCode Server

Open VSCode on the host system, and install an extension called dev-containers, it’s official from Microsoft.

This extension is black magic, it lets us connect to a virtual container, edit code, upload files, and use all the extensions and stuff from our host system (copilot, etc.)

Once installed, to connect to the container we have opened, press CTRL + SHIFT + P. That opens the action searcher. Type “attach to running container”, and press enter. A list of the started containers we have right now will appear. Select the one we want to connect to, and another VSCode window opens with the container’s content. Now, in the file explorer, there is a “Open Folder” button, press it and select the path where the files we want to develop will be found. For example: /home/ubuntu/ros_ws.

Now we can edit the files we want from the comfort of VSCode and they update in real-time inside the container. We can also move files without having to do ssh commands, and even the VSCode terminal is a terminal inside the container.

If we want to change the folder once selected, right-click where the files are, but not on a specific file, and select ‘remove folder from workspace’. The window closes and another one opens with the ‘Open Folder’ button to select the folder where we want to work.

To stop the containers, etc.

To stop the VSCode server, just close the VSCode. If you don’t have autosave enabled, be careful not to leave anything unsaved. The extension does all the magic of managing the connection, etc.

Now just close the container. For that, open docker-desktop and press the stop button, the square. Again, better not to leave anything running and such. The state is saved, even the windows you had open, so the next time you start it you should find everything as it was when you closed it, although just in case, better not leave anything running between turning off and on the container.