From b2b7c4e9a48b1fb767201b1474ad3ea27d76de14 Mon Sep 17 00:00:00 2001 From: Shakirth Anisha Date: Tue, 10 Feb 2026 12:28:32 +0530 Subject: [PATCH 1/3] docs: Add guide for running ROS2 with Docker --- content/guides/ros2/_index.md | 47 +++++ content/guides/ros2/develop.md | 118 +++++++++++ content/guides/ros2/run-ros2.md | 77 ++++++++ content/guides/ros2/turtlesim-example.md | 241 +++++++++++++++++++++++ 4 files changed, 483 insertions(+) create mode 100644 content/guides/ros2/_index.md create mode 100644 content/guides/ros2/develop.md create mode 100644 content/guides/ros2/run-ros2.md create mode 100644 content/guides/ros2/turtlesim-example.md diff --git a/content/guides/ros2/_index.md b/content/guides/ros2/_index.md new file mode 100644 index 000000000000..5d0a73a7864f --- /dev/null +++ b/content/guides/ros2/_index.md @@ -0,0 +1,47 @@ +--- +title: Introduction to ROS 2 Development with Docker +linkTitle: ROS 2 +description: Learn how to containerize and develop ROS 2 applications using Docker. +keywords: ros2, robotics, devcontainers, python, cpp, Dockerfile, rviz +summary: | + This guide details how to containerize ROS 2 applications using Docker. +toc_min: 1 +toc_max: 2 +languages: [] +params: + tags: [frameworks] + time: 30 minutes +--- + +> **Acknowledgment** +> +> This guide is a community contribution. Docker would like to thank +> [Shakirth Anisha](https://www.linkedin.com/in/shakirth-anisha/) for her contribution +> to this guide. + +[ROS 2](https://www.ros.org/) is a set of software libraries and tools for building robot applications. It uses Data Distribution Service (DDS) for real-time, secure communication between distributed nodes, making it ideal for robotics and autonomous systems. + +--- + +## What will you learn? + +In this guide, you'll learn how to: + +- Use official ROS 2 base images from Docker Hub +- Run ROS 2 in an Ubuntu container +- Install ROS 2 packages and dependencies +- Set up a development container for local development +- Run a complete end-to-end example with Turtlesim + +## Prerequisites + +Before you begin, make sure you're familiar with the following: + +- [Docker Desktop](https://docs.docker.com/desktop/): You must have Docker Desktop installed and running. +- [Homebrew](https://brew.sh/) (macOS users): If you are using macOS, you must have Homebrew installed to manage dependencies. +- [Docker concepts](/get-started/docker-concepts/the-basics/what-is-a-container.md): You must understand core Docker concepts, such as images and containers. +- [ROS 2 concepts](https://www.ros.org): Basic understanding of concepts like nodes, packages, topics, and services. + +## What's next? + +Start by setting up your ROS 2 development environment using Docker and dev containers. diff --git a/content/guides/ros2/develop.md b/content/guides/ros2/develop.md new file mode 100644 index 000000000000..9f10abf374bf --- /dev/null +++ b/content/guides/ros2/develop.md @@ -0,0 +1,118 @@ +--- +title: Build and develop a ROS 2 workspace +linkTitle: Set Up ROS 2 workspace +weight: 15 +keywords: ros2, robotics, docker, dockerfile, devcontainer, vscode, workspace +description: Learn how to develop ROS 2 applications using a Docker based workspace and development containers. + +--- + +## Overview + +In this section, you will set up a ROS 2 workspace using Docker and development containers, review the workspace layout, open the workspace in Visual Studio Code, and edit and build ROS 2 projects inside the container. + +--- + +## Get the sample ROS 2 workspace + +A consistent workspace simplifies managing ROS 2 projects and build artifacts across different distributions. + +1. Open a terminal and clone the sample workspace repository: + + ```console + $ git clone https://github.com/shakirth-anisha/docker-ros2-workspace.git + $ cd docker-ros2-workspace + + ``` + + Moving forward, Linux users can use the `ws_linux` folder, and macOS users can use `ws_mac`. + +2. Verify the workspace structure: + + ```text + ws/ + ├── cache/ + | ├── [ROS2_DISTRO]/ + | | ├── build/ + | | ├── install/ + | | └── log/ + | └── ... + | + ├── src/ + ├── .devcontainer/ + │ ├── devcontainer.json + │ └── Dockerfile + ├── package1/ + └── package2/ + + ``` + +3. Explore the workspace layout +- `cache` : Stores build, install, and log artifacts for each ROS 2 distribution. Keeping these directories outside the source tree lets you change distributions without rebuilding everything from scratch. +- `src` : Contains all ROS 2 packages and the development container configuration. This directory is mounted into the container as the active workspace. +- `.devcontainer/` : Holds the configuration used by Visual Studio Code to open the workspace in a container. + - `Dockerfile` : Builds the ROS 2 development image. It uses an official ROS 2 base image, creates a non-root development user, and installs required system and ROS 2 dependencies. + - `devcontainer.json` : Defines how Visual Studio Code builds, runs, and connects to the container. It configures the workspace location, user context, mounted directories, environment variables, networking options, installed extensions, and post-create setup commands. + +## Open and build dev container + +1. Install the `devcontainer` CLI: + + - Linux / Windows + ```console + $ sudo apt update && sudo apt upgrade + $ sudo apt install -y nodejs npm + $ sudo npm install -g @devcontainers/cli + ``` + - macOS + ```console + $ brew install devcontainer + ``` + +2. Execute the following commands to build and start the container: + + ```console + $ devcontainer up --workspace-folder ws/src + + ``` + + This command builds the Docker image defined in your `.devcontainer` folder and starts the container in the background. + + > [!NOTE] + > + > Building the image may take several minutes during the first run + > as the CLI pulls the base ROS 2 image and installs required dependencies. + > Subsequent starts will be significantly faster. + +3. Once the container is running, execute commands inside it using `exec`: + + ```console + devcontainer exec --workspace-folder ws/src /bin/bash + ``` + +4. Inside the container terminal, verify the environment: + +```console +$ ros2 --version +$ which colcon +``` + +All commands should execute successfully inside the container. + +## Switch ROS 2 distributions + +1. Create a new cache directory for the target distribution: + + ```console + $ mkdir -p ~/ws/cache/[ROS_DISTRIBUTION]/{build,install,log} + ``` + +2. Update the cache paths in `src/.devcontainer/Dockerfile` and `src/.devcontainer/devcontainer.json`, changing from `humble` to `ROS_DISTRIBUTION`. + +## Summary + +In this section, you learned how to create a structured workspace with cache directories, write a Dockerfile with development tools and configure a dev container with `devcontainer.json`. Your ROS 2 development environment is now ready with a consistent, reproducible setup across any machine. + +## Next steps + +In the next section, you'll run a complete end-to-end example with Turtlesim. diff --git a/content/guides/ros2/run-ros2.md b/content/guides/ros2/run-ros2.md new file mode 100644 index 000000000000..02740cdf3244 --- /dev/null +++ b/content/guides/ros2/run-ros2.md @@ -0,0 +1,77 @@ +--- +title: Run ROS 2 in a container +linkTitle: Run ROS 2 +weight: 10 +keywords: ros2, robotics, docker, dockerfile, devcontainer, vscode, workspace +description: Run ROS 2 in an isolated Docker container using official ROS 2 images and install additional ROS 2 packages. +--- + +## Overview + +In this section, you will run ROS 2 in an isolated Docker container using official ROS 2 images, verify that ROS 2 is working, and install additional ROS 2 packages for development and testing. + +--- + +## Run ROS 2 in a container + +The fastest way to get started with ROS 2 is to use the [official Docker image](https://hub.docker.com/_/ros/). To pull an image, start a container, and open an interactive bash shell: + +1. Pull and run the official ROS 2 Docker image: + + ```console + $ docker run -it ros:humble + ``` + + This guide uses the Humble distribution. You can replace `humble` with another supported distribution such as `rolling`, `jazzy`, or `iron`. + + > [!Note] + > + > This environment is temporary and does not maintain persistence. + > Any files you create or packages you install will be deleted once the container is stopped or removed. + +2. Verify ROS 2 is working: + + ```console + $ echo $ROS_DISTRO + ``` + + You should see output similar to: + + ```text + humble + ``` + +## Install ROS 2 packages + +The official ROS 2 images include core packages. To install additional packages, use the `apt` package manager: + +1. Update the package manager: + + ```console + $ sudo apt update + ``` + +2. Install the desired package: + + ```console + $ sudo apt install $PACKAGE_NAME + ``` + +Replace `$PACKAGE_NAME` with any package you want to install. + +Some commonly used packages include: + +- `ros-humble-turtlesim` - Visualization and simulation tool +- `ros-humble-rviz2` - 3D visualization tool +- `ros-humble-rqt` - Qt-based ROS graphical tools +- `ros-humble-demo-nodes-cpp` - C++ demo nodes +- `ros-humble-demo-nodes-py` - Python demo nodes +- `ros-humble-colcon-common-extensions` - Build system extensions + +## Summary + +In this section, you pulled an official ROS 2 Docker image, launched an interactive session, and extended the container's capabilities by installing additional ROS 2 packages using apt. + +## Next steps + +In the next section, you will configure a persistent workspace to ensure your code and modifications are saved across sessions. \ No newline at end of file diff --git a/content/guides/ros2/turtlesim-example.md b/content/guides/ros2/turtlesim-example.md new file mode 100644 index 000000000000..555e057aa2b7 --- /dev/null +++ b/content/guides/ros2/turtlesim-example.md @@ -0,0 +1,241 @@ +--- +title: Run a complete example with Turtlesim +linkTitle: Turtlesim example +weight: 20 +keywords: ros2, turtlesim, example, nodes, topics, teleop +description: Run a complete end-to-end ROS 2 example with Turtlesim. +--- + +## Overview + +Turtlesim is a simple simulation tool that demonstrates fundamental ROS 2 concepts such as nodes, topics, and services. In this section, you'll run a complete example with Turtlesim, control the turtle, monitor topics, and visualize the system with rqt. + +--- + +## Configure display forwarding + +### Linux + +Allow Docker access to your X server: + +```console +$ xhost +local:docker +``` + +### macOS + +On macOS, use XQuartz to provide X11 support. Install XQuartz using Homebrew: + +1. Install XQuartz using Homebrew: + + ```console + $ brew install --cask xquartz + ``` + +2. Open XQuartz from Applications, then navigate to `Preferences > Security` and enable `Allow connections from network clients`. Restart your computer to ensure the changes take effect. + +3. After rebooting, open a terminal and allow local connections: + + ```console + $ xhost +localhost + ``` + +> [!Note] +> +> Some ROS 2 visualization tools, such as RViz may be unavailable when using macOS. + +## Start the dev container + +Start the container using the same dev container setup from the workspace section. + +For Linux: +```console +$ devcontainer up --workspace-folder ws_linux/src +$ devcontainer exec --workspace-folder ws_linux/src /bin/bash +``` + +For macOS: +```console +$ devcontainer up --workspace-folder ws_mac/src +$ devcontainer exec --workspace-folder ws_mac/src /bin/bash +``` + +## Install and Run Turtlesim + +Inside the container, install the Turtlesim package: + +1. Update the package manager: + + ```console + $ sudo apt update + ``` + +2. Install the Turtlesim package: + + ```console + $ sudo apt install -y ros-humble-turtlesim + ``` + +3. Run the Turtlesim node: + + ```console + $ ros2 run turtlesim turtlesim_node + ``` + +A window should appear on your desktop showing a turtle in a grid. + +## Control the turtle + +1. Open a new terminal and connect to the same container, then start the keyboard teleop node: + + ```console + $ ros2 run turtlesim turtle_teleop_key + ``` + + This node allows you to control the turtle using your keyboard. Use the arrow keys to move the turtle forward, backward, left, and right. Press `Ctrl+C` to stop the teleop node. + +2. Move the turtle around the window. You should see it draw a path as it moves. + +## Monitor topics + +1. Open another terminal and connect to the same container, then list all active topics: + + ```console + $ ros2 topic list + ``` + + You should see output similar to the following: + + ```text + /parameter_events + /rosout + /turtle1/cmd_vel + /turtle1/color_sensor + /turtle1/pose + ``` + +2. Get information about a specific topic: + + ```console + $ ros2 topic info /turtle1/pose + ``` + + You'll see the topic type and which nodes publish and subscribe to it. + +## Visualize the system with rqt + +1. Open another terminal and connect to the same container, then update the package manager: + + ```console + $ sudo apt update + ``` + +2. Install rqt: + + ```console + $ sudo apt install 'ros-humble-rqt*' + ``` + +3. Start rqt: + + ```console + $ ros2 run rqt_gui rqt_gui + ``` + +An rqt window should appear. rqt provides several useful plugins for visualizing and monitoring ROS 2 systems. + +### Node Graph + +You can explore the node graph by navigating to **Plugins > Introspection > Node Graph**. A new tab opens showing nodes and topics with connections illustrated as lines. This visualization demonstrates how the teleop node sends velocity commands to the Turtlesim node, and how the Turtlesim node publishes position data back through topics. + +### Topic Monitor + +You can monitor active topics by navigating to **Plugins > Topics > Topic Monitor**. A new tab opens displaying all active topics and their current values. Click the eye icon next to `/turtle1/pose` to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands. + +### Message Publisher + +You can also publish messages manually using **Plugins > Topics > Message Publisher**. The Message Publisher plugin allows you to manually publish messages to any topic. You can use it to send velocity commands directly without writing a script. + +### Plots + +To plot topic data over time navigate to **Plugins > Visualization > Plot**. For example, in the Plot window, type `/turtle1/pose/x` in the Topic field and press Enter. Move the turtle and watch the X position displayed as a graph over time. + +## Call ROS 2 services + +Turtlesim provides services for actions such as teleporting the turtle and clearing the path. + +1. List available services: + + ```console + $ ros2 service list + ``` + + You should see services such as `/turtle1/set_pen` (to change pen color and width), `/turtle1/teleport_absolute` (to move the turtle to a specific position), and `/turtle1/teleport_relative` (to move the turtle relative to its current position). + +2. Teleport the turtle to a new position: + + ```console + $ ros2 service call /turtle1/teleport_absolute turtlesim/srv/TeleportAbsolute " + x: 1.0 + y: 3.0 + theta: 0.0 + " + ``` + + The turtle should instantly move to the specified position (3.0, 4.0). + +## Create a simple publisher + +1. Create a Python script that publishes velocity commands to control the turtle programmatically. In a new terminal, create a file called `move_turtle.py`: + + ```python + import rclpy + from geometry_msgs.msg import Twist + import time + + def main(): + rclpy.init() + node = rclpy.create_node('turtle_mover') + publisher = node.create_publisher(Twist, 'turtle1/cmd_vel', 10) + + # Create a twist message + msg = Twist() + msg.linear.x = 2.0 # Move forward at 2 m/s + msg.angular.z = 1.0 # Rotate at 1 rad/s + + # Publish the message + for i in range(50): + publisher.publish(msg) + time.sleep(0.1) + + # Stop the turtle + msg.linear.x = 0.0 + msg.angular.z = 0.0 + publisher.publish(msg) + + node.destroy_node() + rclpy.shutdown() + + if __name__ == '__main__': + main() + ``` + +2. Run the script: + + ```console + $ python3 move_turtle.py + ``` + + The turtle should move in a circular motion for 5 seconds and then stop. + +## Summary + +In this section, you configured display forwarding, used the Turtlesim nodes, inspected nodes and topics, and visualized the system using rqt. Finally, you interacted with ROS 2 services and created a simple publisher to move the turtle programmatically. + +These fundamental concepts apply directly to real-world robotics applications with actual sensors and actuators. + +## Related resources + +- [ROS 2 Turtlesim tutorials](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Topics/Understanding-ROS2-Topics.html) +- [ROS 2 Concepts](https://docs.ros.org/en/humble/Concepts.html) +- [Geometry Messages](https://github.com/ros2/geometry2/tree/humble/geometry_msgs) From a356decdd09fcd6537aaccadcde1f23ac6dad9a0 Mon Sep 17 00:00:00 2001 From: Shakirth Anisha Date: Wed, 11 Feb 2026 09:49:48 +0530 Subject: [PATCH 2/3] Update Vale accept list with ROS2-specific terminology --- _vale/config/vocabularies/Docker/accept.txt | 5 +++++ content/guides/ros2/turtlesim-example.md | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index cdbf04825fac..7c9a82aadf0b 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -179,7 +179,9 @@ Rekor ROCm rollback rootful +rqt runc +RViz Ryuk S3 scrollable @@ -204,11 +206,13 @@ sysctl sysctls Sysdig systemd +teleop Testcontainers tmpfs Traefik Trivy Trixie +Turtlesim Ubuntu ufw umask @@ -231,6 +235,7 @@ WireMock workdir WORKDIR Xdebug +XQuartz youki Yubikey Zscaler diff --git a/content/guides/ros2/turtlesim-example.md b/content/guides/ros2/turtlesim-example.md index 555e057aa2b7..31038e0bbb21 100644 --- a/content/guides/ros2/turtlesim-example.md +++ b/content/guides/ros2/turtlesim-example.md @@ -150,7 +150,7 @@ You can explore the node graph by navigating to **Plugins > Introspection > Node ### Topic Monitor -You can monitor active topics by navigating to **Plugins > Topics > Topic Monitor**. A new tab opens displaying all active topics and their current values. Click the eye icon next to `/turtle1/pose` to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands. +You can monitor active topics by navigating to **Plugins > Topics > Topic Monitor**. A new tab opens displaying all active topics and their current values. Select the eye icon next to `/turtle1/pose` to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands. ### Message Publisher @@ -162,7 +162,7 @@ To plot topic data over time navigate to **Plugins > Visualization > Plot**. For ## Call ROS 2 services -Turtlesim provides services for actions such as teleporting the turtle and clearing the path. +Turtlesim provides services for actions such as repositioning the turtle and clearing the path. 1. List available services: From 81bbf20d66bd43b9330a6450f23c40b98b521fc5 Mon Sep 17 00:00:00 2001 From: Shakirth Anisha Date: Thu, 12 Feb 2026 17:19:37 +0530 Subject: [PATCH 3/3] minor fixes to ros2 guide --- content/guides/ros2/run-ros2.md | 2 +- content/guides/ros2/turtlesim-example.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/guides/ros2/run-ros2.md b/content/guides/ros2/run-ros2.md index 02740cdf3244..e132cb947980 100644 --- a/content/guides/ros2/run-ros2.md +++ b/content/guides/ros2/run-ros2.md @@ -74,4 +74,4 @@ In this section, you pulled an official ROS 2 Docker image, launched an interact ## Next steps -In the next section, you will configure a persistent workspace to ensure your code and modifications are saved across sessions. \ No newline at end of file +In the next section, you will configure a persistent workspace to ensure your code and modifications are saved across sessions. diff --git a/content/guides/ros2/turtlesim-example.md b/content/guides/ros2/turtlesim-example.md index 31038e0bbb21..35133ed8a0cb 100644 --- a/content/guides/ros2/turtlesim-example.md +++ b/content/guides/ros2/turtlesim-example.md @@ -182,7 +182,7 @@ Turtlesim provides services for actions such as repositioning the turtle and cle " ``` - The turtle should instantly move to the specified position (3.0, 4.0). + The turtle should instantly move to the specified position (1.0, 3.0). ## Create a simple publisher