How to Set Up Raspberry Pi 4 for ROS 2 Using Docker (Headless Setup)

 If you’re looking to run ROS 2 on a Raspberry Pi 4 without attaching a monitor or keyboard, this guide is for you. I’ll walk you through a complete headless setup using Docker containers—perfect for robotics projects and remote development.

Step 1: Installing Raspberry Pi OS Lite

For this setup, I always go with Raspberry Pi OS Lite (64-bit). Skipping the desktop environment gives more resources to Docker containers and improves overall performance.

During the SD card imaging process with Raspberry Pi Imager, make sure to:

• Enable SSH for remote access
• Set your username and password
• Configure your WiFi credentials
• Set up locale settings

Lite version:

• Faster performance with containerized apps
• Lower memory usage without desktop overhead
• Works flawlessly with Docker and ROS 2 containers
• Feels like a proper server environment

For the full OS installation steps, follow the official Raspberry Pi documentation.

Step 2: First Boot and Connecting

1. Insert the flashed SD card into your Raspberry Pi 4
2. Connect the power supply and wait 2–3 minutes for the initial boot
3. The Pi should automatically join your configured WiFi network

Step 3: Find Your Pi’s IP Address

Since this is a headless setup, we need the Pi’s IP for SSH. Here’s my approach using an Android phone:

1. Install a network scanner app (my favorites are WOM WiFi, Fing, or Network Scanner by First Row)
2. Make sure your phone is on the same WiFi network as the Pi
3. Run a scan and look for:
4. Hostname: raspberrypi (or your custom name)

• Manufacturer: Raspberry Pi Foundation
• MAC address starting with B8:27:EB, DC:A6:32, or E4:5F:01
• Note down the IP address (e.g., 192.168.1.100)

Pro tip: It usually appears within 1–2 minutes. If not, rescan after a short wait.

Step 4: Connect via SSH

From Linux or Mac:

ssh [username]@[pi-ip-address]
# Example:
ssh pi@192.168.1.100

From Windows (Command Prompt or PowerShell):

ssh [username]@[pi-ip-address]

On first connection:

• You’ll see a host authenticity warning—type yes
• Enter your password set during OS installation
• You should now see the Pi command prompt:

pi@raspberrypi:~ $

Step 5: Initial Setup

Update System Packages

sudo apt update && sudo apt upgrade -y

Enable Interfaces via raspi-config

sudo raspi-config

Enable what you need:

• I2C (for sensors)
• SPI (for devices)
• Camera (if using a Pi camera)

Install Essential Tools

sudo apt install -y curl wget git vim nano htop

These tools make Pi development much smoother.

Step 6: Prepare for Docker

Increase Swap Space (4GB Pi)

sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Change CONF_SWAPSIZE=100 to CONF_SWAPSIZE=1024
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Adjust Memory Split

sudo raspi-config
# Advanced Options -> Memory Split -> set to 16

Step 7: Install Docker

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Add your user to Docker group (no sudo required):

sudo usermod -aG docker $USER

Enable and start Docker service:

sudo systemctl enable docker
sudo systemctl start docker

Test installation:

docker --version
docker run hello-world

Step 8: Add Docker Compose

sudo apt install -y python3-pip
sudo pip3 install docker-compose
docker-compose --version

This is essential for running multi-container applications.

Step 9: VS Code Remote Development

Using VS Code Remote SSH, you can edit files on your Pi as if they were local:

1. Install Remote-SSH extension in VS Code
2. Connect to your Pi:

[username]@[pi-ip-address]

Benefits:

• Full file explorer of the Pi
• Integrated terminal on the Pi
• Code editing with syntax highlighting and IntelliSense
• Extension support for Python, Docker, ROS
• Git integration

Step 10: Troubleshooting

SSH Issues:

• Ensure Pi is powered on and connected
• Re-scan network for IP
• Check /boot/ssh exists
• Try verbose SSH: ssh -v [username]@[pi-ip-address]

VS Code Remote Issues:

• Verify SSH connection works in terminal
• Reinstall Remote-SSH extension if needed
• Restart VS Code

Performance Tips:

• Monitor with htop
• Consider USB 3.0 SSD for heavy workloads
• Ensure proper cooling for extended tasks

Your Raspberry Pi 4 is now ready for ROS 2 development with Docker! Next, we’ll cover:

• Creating custom ROS 2 Docker images for ARM64
• Setting up Docker Compose for robotics projects
• Optimizing containers for Pi’s resources

This headless Raspberry Pi setup with Docker and VS Code gives a lightweight yet powerful development environment. You get full IDE capabilities while keeping the Pi efficient and ready for robotics projects.