Development on Docker

Overview

The fastest and most reliable way to start developing with Kangaroo is to use the Docker images provided by PAL Robotics. These images ship with everything pre-installed and pre-configured so that you do not need to manually set up ROS 2, simulation tools, or any of the robot-specific packages on your host machine.

The PAL Docker images include:

• ROS 2 (the correct distribution for Kangaroo)

• PAL simulation stack using MuJoCo

• All Kangaroo controllers — Joint Trajectory Controller, Whole-Body Control and more

• Visualisation tools — RViz 2, PlotJuggler, rqt

• Build tools — colcon, rosdep, and all required dependencies

Prerequisites

Before running a Docker container you need to meet the following requirements on your host machine:

1. Operating System

Docker on Linux is the supported and recommended platform for running PAL images. The instructions in this section assume Ubuntu 22.04 or Ubuntu 24.04.

2. Docker Engine

Install Docker Engine (not Docker Desktop) by following the official installation guide. After installation, verify it works:

docker --version
docker run hello-world

After installation, add your user to the docker group so that you can run Docker commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Log out and back in for the group change to take full effect.

3. NVIDIA GPU Drivers and Container Toolkit (Optional but Recommended)

If your machine has an NVIDIA GPU, you need two things installed on the host before the GPU is accessible inside Docker:

1. NVIDIA proprietary drivers — so the host OS can talk to the GPU hardware.

2. NVIDIA Container Toolkit — so Docker can pass the GPU through to containers.

Without these, Gazebo, RViz 2, and any other OpenGL or CUDA application will either fail to start or fall back to slow software rendering.

3a. Install NVIDIA Drivers

Check whether drivers are already installed:

nvidia-smi

If the command returns a GPU summary table, drivers are present and you can skip to step 3b. If not, install the recommended driver for your GPU:

sudo apt-get update
sudo apt-get install -y ubuntu-drivers-common
sudo ubuntu-drivers autoinstall
sudo reboot

After rebooting, verify the installation:

nvidia-smi

3b. Install the NVIDIA Container Toolkit

The NVIDIA Container Toolkit adds GPU support to the Docker runtime. Install it by configuring the NVIDIA package repository and then installing the package:

# Add the NVIDIA package repository GPG key and repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Install the toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

After installation, configure Docker to use the NVIDIA runtime and restart the daemon:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

3c. Verify GPU Access Inside Docker

Run the following one-liner to confirm that Docker can see your GPU:

docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

The output should show your GPU model, driver version, and CUDA version — the same as running nvidia-smi directly on the host. If it does, GPU acceleration is fully configured.

Tip

If you have multiple GPUs and only want to expose a specific one, use --gpus '"device=0"' instead of --gpus all. The pal_docker.sh script uses --gpus all by default.

4. GitLab Account with Repository Access

The PAL Docker images are hosted in the GitLab Container Registry. You need a GitLab account that has been granted access to the Kangaroo repository. Contact your PAL Robotics support contact to request access if you do not have it yet.

Where to Find the Images

Once you have repository access, navigate to your Kangaroo project on gitlab.com and open:

Left sidebar → Packages → Container Registry

You will see all available images. Use the copy button next to an image to copy its full registry URL — you will need this URL in the next step.

Image tags follow the convention <branch-or-release>-<date>. For day-to-day development, use the image corresponding to the ros2 branch or the latest stable release tag provided by PAL.

Workflow Summary

The typical development workflow with Docker is:

Pull image → Start container → Develop & test → Save work to exchange folder

All files you create inside the container that are not in the exchange folder will be lost when the container stops. See Running the Docker Container for details on how to persist your work.