Docs Beginners Workspace repo
Docs menu

Development Environment Setup

Set up the Racerbot ROS 2 development environment on macOS, Linux or Windows: Docker Desktop, the racerbot_ws workspace container, verification checkpoints and troubleshooting.

This guide takes you from a fresh machine to a working Racerbot development environment: the same ROS 2 Humble workspace the team develops in, running in a Docker container so it works identically on macOS, Linux and Windows. Everything below is checked against the racerbot_ws repository, the team’s own setup docs and the official Docker and ROS 2 documentation (sources at the bottom).

Budget about 45 to 60 minutes, most of it waiting on downloads. Each stage ends with a checkpoint - a command and the output you should see. Do not move on until the checkpoint passes; the troubleshooting section at the bottom is organized by symptom.

What you are building

  • Docker Desktop runs a container: a self-contained Ubuntu 22.04 with ROS 2 Humble preinstalled.
  • The container holds the team workspace, /racerbot_ws. Your code lives in the src folder, which is shared with your computer, so you edit files on your machine and build them inside the container.
  • Later guides build on this: the simulator connects to this workspace, and Lab 1 assumes it builds.

You do not install ROS 2 on your computer itself. That is deliberate: the container is the same for every member on every OS, so “works on my machine” stops being a thing.

1. Prerequisites

Every OS needs:

  • Git. Check with git --version. macOS: it ships with the system, or xcode-select --install. Windows: git-scm.com. Linux: your package manager, e.g. sudo apt install git.
  • Docker Desktop. Install it from the official page for your OS:
  • About 10 GB of free disk for the image and build files.
Windows: run every command in this guide in PowerShell, not Command Prompt. The line-continuation character in PowerShell is the backtick `, which is why the Windows docker run command below looks different from the macOS/Linux one.

Checkpoint: start Docker Desktop and wait until it reports it is running. Then in a terminal:

docker version

You should see both a Client and a Server section with version numbers. If you get “Cannot connect to the Docker daemon”, Docker Desktop is not running yet - see troubleshooting.

2. Clone the workspace

Pick a folder to keep team work in, then clone:

git clone https://github.com/sfu-racerbot/racerbot_ws.git
cd racerbot_ws

Checkpoint: ls shows the repo contents, including a .devcontainer folder. That folder’s Dockerfile is what the next step builds: it starts from the official ros:humble image (Ubuntu 22.04 + ROS 2 Humble) and adds tmux, editors and the workspace user.

3. Build the image

docker build -f .devcontainer/Dockerfile -t racerbot .

The first build downloads several gigabytes. Later builds reuse the cache and finish in seconds.

Checkpoint:

docker images

racerbot appears in the list.

4. Run the container

macOS / Linux:

docker run -it \
--name racerbot \
-p 127.0.0.1:8765:8765 \
-v $(pwd)/src:/racerbot_ws/src \
-v racerbot_ws_build:/racerbot_ws/build \
-v racerbot_ws_install:/racerbot_ws/install \
-v racerbot_ws_log:/racerbot_ws/log \
racerbot

Windows (PowerShell):

docker run -it `
--name racerbot `
-p 127.0.0.1:8765:8765 `
-v "${PWD}/src:/racerbot_ws/src" `
-v racerbot_ws_build:/racerbot_ws/build `
-v racerbot_ws_install:/racerbot_ws/install `
-v racerbot_ws_log:/racerbot_ws/log `
racerbot

What the flags do, briefly: --name racerbot names the container so you can restart it later; -p 127.0.0.1:8765:8765 forwards the port the simulator’s Foxglove bridge uses; the -v flags share your src folder with the container and keep build output in Docker volumes so it survives rebuilds.

Checkpoint: your prompt changes - you are now inside the container as user rosdev, in /racerbot_ws. Leaving the terminal (or typing exit) stops the container; that is normal.

5. Install dependencies and build

Inside the container:

cd /racerbot_ws
sudo apt update && sudo apt upgrade -y
rosdep update
rosdep install --from-paths src --ignore-src -r -y
colcon build
source install/setup.bash

rosdep reads every package in src and installs what it needs; colcon build compiles the workspace; source puts the built packages on your ROS 2 path.

Checkpoint:

ros2 --version

prints a ROS 2 release line, and ros2 pkg list | head lists packages. If you have no packages in src yet, colcon build finishing without errors is the checkpoint.

6. Day-to-day: starting a session

The docker run command is once-only. From now on:

docker start -ai racerbot

then inside the container, source the environment in every new terminal or tmux window:

source /opt/ros/humble/setup.bash
source /racerbot_ws/install/local_setup.bash

The team’s workflow doc shows the full session pattern with tmux; the terminal foundations guide covers tmux, sourcing and friends if those are new.

7. Optional: VS Code inside the container

If you use VS Code, the smoothest workflow is editing on your machine and attaching VS Code to the running container:

  1. Install the Dev Containers extension (plus Python and C/C++ for ROS work).
  2. Open the racerbot_ws folder in VS Code.
  3. Cmd/Ctrl+Shift+P → “Dev Containers: Attach to Running Container” → pick racerbot.
  4. Reinstall your extensions inside the container when prompted - extensions do not always follow automatically.

Do not use “Reopen in Container” on a fresh folder: it builds a second container instead of attaching to yours.

Platform notes

  • macOS: there is no practical native ROS 2 on macOS, which is exactly why the team uses Docker. On Apple silicon the ros:humble image runs through Docker’s emulation; builds are slower than on Intel but fully working.
  • Windows: keep the workspace on your Windows drive and open it in PowerShell as above. Docker Desktop’s WSL 2 backend handles the Linux side. If Docker Desktop asks you to install or update WSL 2, say yes and reboot when told.
  • Linux: Docker Engine (without Desktop) is fine. If docker version gives you a permission error on the daemon socket, add yourself to the docker group (sudo usermod -aG docker $USER, then log out and back in).
  • A car computer (Jetson): this guide sets up a development container on your own machine. When a car’s Jetson needs a full rebuild or reflash, follow the team guide: NVIDIA Jetson setup.

Troubleshooting

Symptom-based. Find your error, apply the fix, re-run the checkpoint for that stage.

Cannot connect to the Docker daemon at ... Is the docker daemon running? Docker Desktop is not running. Start it and wait for it to report “running” before retrying.

docker: permission denied while trying to connect to the Docker daemon socket (Linux) Your user is not in the docker group: sudo usermod -aG docker $USER, then log out and log back in.

docker: Error response from daemon: Conflict. The container name "/racerbot" is already in use The container already exists - you only run it once. Use docker start -ai racerbot instead. To genuinely start over: docker rm racerbot, then the docker run command again.

Bind for 127.0.0.1:8765 failed: port is already allocated Another container (usually an older racerbot one) holds the port. docker ps to see it, docker stop <name> to stop it, then retry.

docker build fails with a network error partway through Transient download failures are common on campus Wi-Fi. Re-run the same command; Docker resumes from the last completed layer.

rosdep install cannot fetch package lists Run rosdep update first, and make sure you are inside the container (prompt shows the container user, path is /racerbot_ws).

colcon build fails with a missing package error A dependency was not installed. Re-run rosdep update && rosdep install --from-paths src --ignore-src -r -y, then colcon build again.

ros2: command not found inside the container You have not sourced ROS 2 in this terminal: source /opt/ros/humble/setup.bash (and source /racerbot_ws/install/local_setup.bash for your own packages). Every new terminal needs this.

Your edits in src do not show up inside the container You probably started the container from a different folder, so a different src got mounted. exit, cd into your real racerbot_ws, and docker start -ai racerbot again.

Windows: files cloned with CRLF line endings break scripts inside the container Tell Git to check out Unix line endings for this repo: from the repo root, git config core.autocrlf input, then re-clone or git add --renormalize ..

Apple silicon Mac: colcon build is very slow or a package crashes with an illegal-instruction error The container is emulating x86. Make sure Rosetta is installed (softwareupdate --install-rosetta --agree-to-license) and, in Docker Desktop settings, that the Rosetta x86 emulation option is enabled.

Sources

Next: get a simulated race running with the simulator quickstart.