Build ROS/ROS2 Development Environment with Docker - Complete Guide

September 8, 2024 · 6 min read

R&D Researcher, Control & Robotics

Building a ROS development environment with Docker solves environment dependency issues and allows using multiple ROS versions on the same system. This guide explains in detail how to build a ROS environment with Docker.

Docker + ROS

1. Docker Installation

Installation Using APT Repository

Install Docker from the official Docker APT repository.

1.1 Prerequisites

# 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

1.2 Add Repository

# Add 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

1.3 Install Docker

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

1.4 Verify Installation

sudo docker run hello-world

About Docker Desktop

Do not install Docker Desktop on Ubuntu. Docker Engine is sufficient.

2. ROS Docker Images

Official ROS Images

Official ROS images can be obtained from Docker Hub.

ROS1 Noetic

sudo docker pull osrf/ros:noetic-desktop-full

ROS2 Humble

sudo docker pull osrf/ros:humble-desktop-full

Other ROS Distributions

# ROS1 Melodic
sudo docker pull osrf/ros:melodic-desktop-full

# ROS2 Galactic
sudo docker pull osrf/ros:galactic-desktop-full

# ROS2 Iron
sudo docker pull osrf/ros:iron-desktop-full

Available Tags

Tag	Contents
`ros-core`	Minimal ROS installation
`ros-base`	Basic ROS packages
`desktop`	ROS Desktop (includes RViz)
`desktop-full`	Full ROS Desktop (includes simulators)

3. Creating ROS Containers

3.1 X11 Forwarding Setup

Configuration for using GUI applications (RViz, Gazebo, VS Code):

xhost +

Automation Tip

You need to run this command every time you restart the container.

3.2 Create Data Folder

Create a folder for sharing files between host and container:

mkdir ~/ros_workspace

3.3 Create ROS1 Noetic Container

sudo docker run -it \
    -v ~/ros_workspace:/data \
    --device=/dev/dri \
    --group-add video \
    --volume=/tmp/.X11-unix:/tmp/.X11-unix \
    --env="DISPLAY=$DISPLAY" \
    --env="QT_X11_NO_MITSHM=1" \
    --name=noetic_container \
    osrf/ros:noetic-desktop-full \
    /bin/bash

3.4 Create ROS2 Humble Container

sudo docker run -it \
    -v ~/ros_workspace:/data \
    --device=/dev/dri \
    --group-add video \
    --volume=/tmp/.X11-unix:/tmp/.X11-unix \
    --env="DISPLAY=$DISPLAY" \
    --env="QT_X11_NO_MITSHM=1" \
    --name=humble_container \
    osrf/ros:humble-desktop-full \
    /bin/bash

Detailed Parameter Explanation

Parameter	Description
`docker run`	Create and run new container
`-it`	Interactive terminal mode
`-v ~/ros_workspace:/data`	Mount host directory to container
`--device=/dev/dri`	Access to graphics device
`--group-add video`	Add to video group (for GPU access)
`--volume=/tmp/.X11-unix:/tmp/.X11-unix`	Mount X11 socket
`--env="DISPLAY=$DISPLAY"`	Set display environment variable
`--env="QT_X11_NO_MITSHM=1"`	Avoid Qt application display issues
`--name=<container_name>`	Assign name to container

4. ROS Environment Setup Inside Container

4.1 System Update

sudo apt update
sudo apt upgrade

4.2 Install Required Tools

Tmux (Terminal Multiplexer)

apt install tmux

Basic Tmux usage:

New session: tmux new -s session_name
List sessions: tmux list-sessions
Attach to session: tmux attach -t session_name

Git (Version Control)

apt install git

Additional Development Tools

# Editors
apt install vim nano

# Build tools
apt install build-essential cmake

# Python tools
apt install python3-pip python3-dev

# ROS build tools
apt install python3-catkin-tools  # For ROS1
apt install python3-colcon-common-extensions  # For ROS2

4.3 Verify ROS Environment

ROS1 Verification

Start roscore
```
roscore
```
Launch RViz (in new terminal)
```
rviz
```
Launch Gazebo (in new terminal)
```
gazebo
```

ROS2 Verification

Run demo_nodes_cpp
```
ros2 run demo_nodes_cpp talker
```
Run listener in another terminal
```
ros2 run demo_nodes_cpp listener
```
Launch RViz2
```
rviz2
```

5. Workspace Setup

ROS1 Workspace

# Create workspace
mkdir -p /data/catkin_ws/src
cd /data/catkin_ws

# Initialize workspace
catkin_make

# Add environment setup
echo "source /data/catkin_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

ROS2 Workspace

# Create workspace
mkdir -p /data/ros2_ws/src
cd /data/ros2_ws

# Build workspace
colcon build

# Add environment setup
echo "source /data/ros2_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

6. Network Configuration

ROS1 Master Configuration

# Set environment variables
export ROS_MASTER_URI=http://localhost:11311
export ROS_HOSTNAME=localhost

ROS2 Domain ID Configuration

# Set domain ID (for network isolation)
export ROS_DOMAIN_ID=42

7. Container Management

Start and Stop Containers

# Start container
sudo docker start -ia noetic_container

# Stop container
sudo docker stop noetic_container

# Connect with multiple terminals
sudo docker exec -it noetic_container /bin/bash

Create Container Snapshot

# Save current state as an image
sudo docker commit noetic_container my_ros_environment:v1.0

8. Docker Compose Configuration Example

Docker Compose configuration for managing multiple ROS services:

version: '3.8'

services:
  ros-master:
    image: osrf/ros:noetic-desktop-full
    container_name: ros_master
    environment:
      - DISPLAY=${DISPLAY}
      - QT_X11_NO_MITSHM=1
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
      - ./workspace:/workspace
    devices:
      - /dev/dri:/dev/dri
    networks:
      - ros_network
    command: roscore

  rviz:
    image: osrf/ros:noetic-desktop-full
    container_name: rviz_container
    environment:
      - DISPLAY=${DISPLAY}
      - QT_X11_NO_MITSHM=1
      - ROS_MASTER_URI=http://ros-master:11311
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
    devices:
      - /dev/dri:/dev/dri
    networks:
      - ros_network
    depends_on:
      - ros-master
    command: rviz

networks:
  ros_network:
    driver: bridge

9. Troubleshooting

Common Issues and Solutions

1. GUI Applications Don't Display

# Check X11 forwarding
echo $DISPLAY

# Check xhost settings
xhost +local:

# Qt-related errors
export QT_X11_NO_MITSHM=1

2. GPU Access Errors

# Check NVIDIA drivers
nvidia-smi

# Install Docker nvidia runtime
sudo apt install nvidia-docker2
sudo systemctl restart docker

3. Network Connection Issues

# Check ROS network settings
echo $ROS_MASTER_URI
echo $ROS_HOSTNAME

# Check firewall settings
sudo ufw status

10. Performance Optimization

Reduce Image Size

# Multi-stage build example
FROM osrf/ros:noetic-desktop-full as builder
# Install build packages
RUN apt-get update && apt-get install -y build-essential

FROM osrf/ros:noetic-desktop-full
# Copy only minimal runtime packages
COPY --from=builder /opt/ros/noetic /opt/ros/noetic

Memory and CPU Limits

# Start container with resource limits
docker run -it \
    --memory="4g" \
    --cpus="2.0" \
    --name=limited_ros \
    osrf/ros:noetic-desktop-full

References

Development Efficiency Tips

Use VS Code Remote-Containers extension
Maintain consistent directory structure for ROS package development
Standardize development environment with Docker Compose
Use .dockerignore files to reduce build time

1. Docker Installation​

Installation Using APT Repository​

1.1 Prerequisites​

1.2 Add Repository​

1.3 Install Docker​

1.4 Verify Installation​

2. ROS Docker Images​

Official ROS Images​

ROS1 Noetic​

ROS2 Humble​

Other ROS Distributions​

Available Tags​

3. Creating ROS Containers​

3.1 X11 Forwarding Setup​

3.2 Create Data Folder​

3.3 Create ROS1 Noetic Container​

3.4 Create ROS2 Humble Container​

Detailed Parameter Explanation​

4. ROS Environment Setup Inside Container​

4.1 System Update​

4.2 Install Required Tools​

Tmux (Terminal Multiplexer)​

Git (Version Control)​

Additional Development Tools​

4.3 Verify ROS Environment​

ROS1 Verification​

ROS2 Verification​

5. Workspace Setup​

ROS1 Workspace​

ROS2 Workspace​

6. Network Configuration​

ROS1 Master Configuration​

ROS2 Domain ID Configuration​

7. Container Management​

Start and Stop Containers​

Create Container Snapshot​

8. Docker Compose Configuration Example​

9. Troubleshooting​

Common Issues and Solutions​

1. GUI Applications Don't Display​

2. GPU Access Errors​

3. Network Connection Issues​

10. Performance Optimization​

Reduce Image Size​

Memory and CPU Limits​

References​