Running ROS 2 With Docker on Raspberry Pi - My Guide to Optimized Performance

Now that I have my Raspberry Pi 4 set up with Docker and VS Code remote development, it's time for the exciting part - running ROS 2 in containers! In this article, I'll share how I build and optimize ROS 2 Docker containers specifically for the Pi's ARM64 architecture and resource constraints.

Why I Love Using Docker for ROS 2 on Pi

Before diving into the technical details, let me explain why this approach has become my go-to method:

1. Consistent environments - My containers work the same way across different Pi setups
2. Easy deployment - I can build once and deploy anywhere
3. Resource isolation - Each ROS node runs in its own container with controlled resources
4. Version management - I can run multiple ROS 2 versions side-by-side
5. Clean development - No more dependency conflicts or messy installations

What you'll need

Before we start, here's what I used for this setup:

1. Raspberry Pi 4
2. Power supply for the Pi 4
3. Stable internet connection
4. Host PC with Linux/Windows/Mac

The first thing I learned when working with Docker on Pi is that not all Docker images work out of the box. The Raspberry Pi 4 uses an ARM64 architecture, so I need ARM64-compatible images.

Checking my Pi's architecture

I always verify my Pi's architecture first:

This should return aarch64, confirming I'm running 64-bit ARM.

Finding ARM64 ROS 2 Images

I use the official ROS Docker images that support ARM64:

It checks locally for the image on the Pi first. If it's not there, it starts downloading the image. Docker automatically pulls the ARM64 architecture version of the image for my Pi.

You'll see output like:

I can verify the image is downloaded correctly with:

Here's how I create my first ROS 2 container optimized for the Pi:

My Basic ROS 2 Dockerfile

I create a file called dockerfile.ros2-pi:

Building my Container

First, I build the container:

I usually grab a coffee during this build - it takes 10-15 minutes on the Pi.

Running the Container Interactively

I like to start with an interactive container to test things out:

This gives me a bash prompt inside the container where I can run ROS 2 commands directly.

Adding volume mounts for development:

For actual development work, I usually want to share my code between the Pi and the container:

What this does:

1. -v /home/pi/my_ros2_workspace:/ros2_ws - Mounts my Pi's workspace folder into the container
2. Any changes I make in VS Code (connected to the Pi) appear instantly in the container
3. Built packages persist even if I delete the container

Connecting from a second terminal

If my container is already running, I can connect to it from another terminal window:

This is incredibly useful when I want to:

1. Run multiple ROS 2 nodes in the same container
2. Monitor logs while running commands
3. Debug issues while keeping the main process running

Running in Background Mode

For production, I run containers in the background:

Then I can still connect to the container anytime with the docker exec command above.

The Pi has limited resources compared to a desktop computer, so I've implemented several strategies to make my containers run efficiently. Here's what I've learned works best:

Memory Optimization

The Pi 4 has either 4GB or 8GB of RAM, which needs to be shared between the OS and all running containers.

I always set memory limits for my containers to prevent one container from using all available RAM:

What this does:

1. --memory=1g: Limits RAM usage to 1GB
2. --memory-swap=2g: Allows up to 1GB additional swap space
3. Prevents the container from crashing the Pi by using all the memory

CPU Optimization

The Pi 4 has a quad-core CPU, but ROS 2 nodes can be CPU-intensive.

For CPU-intensive nodes, I limit CPU usage:

I can also set CPU priority:

What this does:

1. Prevents one container from monopolizing all CPU cores
2. Ensures the Pi remains responsive for other tasks
3. Helps with thermal management (less heat generation)

Storage Optimization

SD cards have limited space and slower I/O compared to SSDs.

I use .dockerignore to keep build contexts small.

And I clean up after package installations:

My Multi-Stage Docker Build Approach

Why I use this: It dramatically reduces the final image size by excluding build tools and temporary files.

To keep container sizes small, I use multi-stage builds:

Before building, create the directory:

Running with your workspace mounted:

For development work, I mount my workspace directory:

Why use a multi-stage build approach?

1. Final image is 50-70% smaller
2. Faster deployment and updates
3. Less storage usage on the Pi
4. Clean separation of build and runtime environments

What is Docker Compose and Why Do I Need It?

Think of Docker Compose as a way to manage multiple containers like they're one application. Instead of running separate docker run commands for each ROS 2 node (which gets messy fast), I wrote one configuration file that describes all my containers and how they work together.

Why I love Docker Compose for ROS 2:

1. One command starts everything: docker-compose up starts my entire robot system
2. Automatic networking: All containers can talk to each other automatically
3. Dependency management: Containers start in the right order
4. Easy scaling: I can run multiple copies of the same node
5. Simplified development: Changes to one container don't affect others

For complex robotics projects, I use Docker Compose to manage multiple ROS 2 nodes:

My ROS 2 Docker Compose Setup

Now, let's create a practical example using the official ROS 2 talker and listener nodes from the Writing a simple publisher and subscriber (Python) tutorial. I'll setup Docker Compose to run both nodes in separate containers.

Create a ROS 2 package py_pubsub, inside /home/pi/my_ros2_workspace/src by following the steps from here

I create a docker-compose.yml file:

Starting my Multi-Node System

From the directory where the docker-compose.yml was created, run:

What this setup demonstrates:

1. Talker node: Publishes "Hello World" messages every 0.5 seconds to the 'topic' topic
2. Listener node: Subscribes to the 'topic' topic and prints received messages
3. Automatic building: Each container builds the package before running
4. Volume mounting: Source code is shared between the host and containers
5. Network communication: Both containers use host networking for ROS 2 discovery

I can monitor all my nodes with:

You will see output like:

Stopping Multi-Node systems

To stop and clean up all containers:

Other useful Docker Compose commands:

DDS Configuration for Pi

What is this, and where do I create it?

DDS (Data Distribution Service) is how ROS 2 nodes communicate with each other. The default settings are designed for powerful computers, but the Pi needs more conservative settings to avoid overwhelming its network and memory.

I create a custom DDS configuration file called cyclonedds.xml in my project directory (the same folder as my dockerfile):

What this does:

1. WhcHigh/WhcLow: Limits memory used for message queues (default can be 100MB+)
2. Peers: Tells DDS to only look for other nodes on the same Pi
3. ParticipantIndex: Let's DDS automatically assign participant IDs

How to use it in my containers:

In my Docker Compose file:

Why this helps:

1. Reduces memory usage by 80-90%
2. Faster node startup times
3. More reliable communication on Pi's limited network

GPU Access for Computer Vision

When I need GPU acceleration for computer vision tasks:

I2C and GPIO Access

For hardware interfacing:

Checking Container Performance

I regularly monitor my container's resource usage:

Debugging Container Issues

For troubleshooting, I exec into running containers:

Then I can check ROS 2 nodes:

My Log Management Strategy

I configure log rotation to prevent storage issues:

Network Performance

Default Docker networking adds overhead that the Pi can't handle well.

I use host networking for ROS 2 containers:

Trade-offs:

1. Pro: 20-30% better network performance
2. Pro: Simpler ROS 2 discovery (no port mapping needed)
3. Con: Less container isolation
4. Con: Potential port conflicts

When I use each:

1. Host networking: For ROS 2 communication (always)
2. Bridge networking: For web services, databases (when isolation matters)

CPU Thermal Management

The Pi throttles the CPU when it gets too hot, causing the containers to run slowly.

We can monitor using:

My Docker prevention strategy:

Container won't start

1. Check the Pi's available memory with free -h
2. Verify the image architecture matches ARM64
3. Look at container logs with docker logs container_name

ROS 2 Nodes can't communicate

1. Ensure all containers use the same ROS_DOMAIN-ID
2. Verify network_mode is set to host
3. Check firewall settings with sudo ufw status

Poor Performance

1. Monitor CPU usage with htop
2. Check if containers are swapping with docker stats
3. Verify adequate cooling (Pi can throttle when hot)

Running ROS 2 in Docker containers on the Raspberry Pi has transformed the way to develop robotics projects. The combination of containerization and proper resource optimization gives me:

1. Consistent, reproducible deployments
2. Better resource management
3. Easier debugging and monitoring
4. Scalable multi-node architectures

The key is to understand the Pi's limitations and optimize accordingly. With these techniques, I can run surprisingly complex ROS 2 systems on a single Pi 4.

Github Repository

All the files, Dockerfiles, and configurations mentioned in this article are available in my GitHub repository: https://github.com/nilutpolkashyap/ros2-docker-arm64