Ubuntu Environment

You have two paths to a working BPC-PRP environment:

  • Path A — Docker dev container (recommended). One command, the same environment as the reference solution, runs on any host that can run Docker. See § Docker dev container below.
  • Path B — Native Ubuntu install. Full Ubuntu + ROS 2 on bare metal or a VM. More steps, but no container overhead. See § Native install.

Both paths land you in a Linux shell with a C++ toolchain and ROS 2; the rest of the labs do not care which you picked.

Path A — Docker dev container

The course ships a layered Docker image set. For Labs 1–13 you need the student-dev image: ROS 2 Jazzy on Ubuntu 24.04 with the C++ toolchain, RViz2, rqt, image_transport_plugins, and the C++ project template baked in.

Prerequisites

  • Docker Engine ≥ 24.0 or Docker Desktop. Install per the official docs: https://docs.docker.com/engine/install/.

  • On Linux, add your user to the docker group so you do not need sudo:

    sudo usermod -aG docker $USER
newgrp docker            # apply the new group without re-login
docker run hello-world   # verify

  • Roughly 5 GB of free disk space for the image set.

Build the images (one-time)

From the BPC-PRP repo root:

# base image (the others layer on this)
docker build \
  --build-arg UID=$(id -u) --build-arg GID=$(id -g) \
  -t bpc-prp-base:jazzy \
  docker/base

# student-dev image (used by VS Code dev container and docker compose)
docker build \
  -f docker/student-dev/Dockerfile \
  -t bpc-prp-student-dev:jazzy \
  .

Both builds together take roughly 10 – 15 min on a first run, depending on your network speed.

Robotics-BUT members: pre-built images are also published to GHCR at ghcr.io/robotics-but/bpc-prp-{base,student-dev}:jazzy. The packages are private; pull requires docker login ghcr.io with a GitHub token that has read:packages. For students outside the org, the local build above is the supported path.

Option 1 — VS Code Dev Containers (recommended)

  1. Install VS Code and the Dev Containers extension (ms-vscode-remote.remote-containers).
  2. git clone https://github.com/Robotics-BUT/BPC-PRP.git && cd BPC-PRP
  3. code .
  4. VS Code prompts to Reopen in Container (or run the command from the Command Palette). The repo is mounted at /workspace; the C++ + ROS extensions are auto-installed.

The C++ project template sits at /workspace/bpc-prp-cpp-project-template/ inside the container; copy it to start your team project.

Option 2 — docker compose (no VS Code)

# Linux + X11 host — once per session, allow the container to reach X:
xhost +local:docker

# from the BPC-PRP repo root:
docker compose up -d
docker compose exec dev bash

# inside the container:
cp -r /opt/bpc-prp/template my-project
cd my-project
colcon build --cmake-args -DBUILD_TESTING=ON
source install/setup.bash
rviz2   # GUI works through the host's X server

Verify

In the container shell:

ros2 --version             # expect: jazzy
ros2 doctor --report-level
gcc --version              # gcc 13.x
cmake --version            # cmake 3.28.x

Troubleshooting (Docker path)

  • could not connect to display — host X11 not exposed. Run xhost +local:docker. Verify DISPLAY is set inside the container with docker compose exec dev printenv DISPLAY.
  • Wayland sessions — usually work through XWayland with the same xhost trick. If not, fall back to an X11 session or run RViz / rqt outside the container against a workspace built inside it.
  • macOS / Windows — network_mode: host does not behave the same. Linux is the supported host; on macOS / Windows the bridged-network approach with XQuartz / VcXsrv / WSLg works but is out of scope here.

For the full reference see docker/student-dev/README.md in the repo.

Path B — Native Ubuntu install

The rest of this chapter sets up a fresh Ubuntu 22.04 LTS machine for the BPC-PRP course toolchain: a C++ compiler, CMake, Git, ROS 2 Humble, and one of the supported IDEs (CLion or Visual Studio Code). Run the steps in order; verification commands follow each step.

Path B currently targets ROS 2 Humble on Ubuntu 22.04. A follow-up of the modernization roadmap (T2.4) will rewrite this for Jazzy / 24.04 once the robot stack itself flips to Jazzy.

Prerequisites

  • Ubuntu 22.04 LTS (Jammy), x86_64. Other releases or distros may work but are not the supported configuration — ROS 2 Humble's binary packages target 22.04.
  • Internet access for apt and Snap.
  • ≈ 10 GB free disk space for ROS 2 + dev tools.

Verify the release:

lsb_release -a
# Expected: Ubuntu 22.04.x LTS, codename: jammy

1. Update and (optional) swap

Update the package index and upgrade installed packages:

sudo apt update
sudo apt upgrade -y

On a laptop with limited RAM (≤ 8 GB), add a 16 GB swap file before installing ROS 2 — colcon build is memory-hungry and can OOM-kill compilers on small machines:

sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
sudo swapon --show           # verify the swap is active

To keep the swap across reboots, append this line to /etc/fstab:

/swapfile none swap sw 0 0

2. Basic dev tools

sudo apt install -y \
    build-essential cmake clang \
    git openssh-server \
    vim nano htop tree mc net-tools

What each gives you:

  • build-essential — GCC and the standard build dependencies; the system C/C++ compiler.
  • cmake — the build system the labs use.
  • clang — alternative C++ compiler; often clearer diagnostics than GCC.
  • git, openssh-server — version control and remote access.
  • vim, nano — terminal editors; htop, tree, mc, net-tools — convenient diagnostics.

Verify:

g++ --version       # expect 11.x or newer
cmake --version     # expect 3.22 or newer
git --version       # expect 2.34 or newer

3. Locale

ROS 2 needs a UTF-8 locale:

sudo apt install -y locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
locale              # verify LC_ALL=en_US.UTF-8

4. ROS 2 apt repository

Add the ROS 2 archive key and source list:

sudo apt install -y software-properties-common curl
sudo add-apt-repository universe -y

sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
    -o /usr/share/keyrings/ros-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" \
    | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

5. Install ROS 2 Humble

sudo apt update
sudo apt install -y ros-humble-desktop ros-dev-tools
sudo apt install -y ros-humble-image-transport-plugins

Source ROS 2 in every interactive shell — append to ~/.bashrc:

echo 'source /opt/ros/humble/setup.bash' >> ~/.bashrc
source ~/.bashrc

Verify the installation:

ros2 --version            # expect "humble"
ros2 doctor --report      # full diagnostic; expect no critical errors

Quick end-to-end smoke test — in one terminal:

ros2 run demo_nodes_cpp talker

In a second terminal:

ros2 run demo_nodes_cpp listener

The listener prints messages from the talker. Stop both with Ctrl+C.

6. IDE

Install one (or both) of:

sudo snap install --classic clion       # full-featured CMake IDE; free with a student licence
sudo snap install --classic code        # Visual Studio Code; lighter, more extensible

See CLion and Visual Studio Code for the recommended extensions and project setup.

7. Verify the full stack

Build a tiny ROS 2 workspace from scratch:

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
ros2 pkg create --build-type ament_cmake hello_ros
cd ~/ros2_ws
colcon build --packages-select hello_ros
source install/setup.bash
ros2 pkg list | grep hello_ros          # expect "hello_ros"

If colcon build succeeds and ros2 pkg list shows hello_ros, your environment is ready for Lab 1.

Troubleshooting

ros2: command not found → you did not source the ROS 2 setup. Run source /opt/ros/humble/setup.bash and add it to ~/.bashrc.

E: Unable to locate package ros-humble-desktop → the ROS 2 apt repo is not configured. Re-do Step 4, then sudo apt update.

Couldn't connect to packages.ros.org → behind a corporate firewall or proxy. Configure apt proxy in /etc/apt/apt.conf.d/95proxy and re-run.

colcon build runs out of memory → add the swap file from Step 1, or build a single package at a time with colcon build --packages-select <name>.

Locale errors / WARNING: Could not setlocale from Python → re-run Step 3 in a new terminal so the new locale takes effect.

Inspect what is installed:

apt list --installed 2>/dev/null | grep ros-humble | head -10

Out of scope