Setup Guide (Docker Version)

auv-software: Docker Workspace Setup

Welcome! This guide will walk you through setting up the AUV software stack in the Docker container. Whether you're a new team member or setting up a fresh machine, you'll have everything running in no time.

Docker vs. Normal Setup

The normal setup guide requires Ubuntu 20.04, but with the Docker setup you can use any recent Linux — you don't have to install Ubuntu 20.04 on your machine. That matters because fully supporting newer hardware (e.g. new-generation Intel iGPUs) on Ubuntu 20.04 is difficult: its old drivers and libraries often break on modern laptops. The container still runs Ubuntu 20.04 + ROS Noetic, so the software behaves exactly like the real setup — but your host system stays as you like it.

What You'll Need

Before we start, make sure you have:

• Docker installed on your host machine
• The container image — it already includes Ubuntu 20.04, ROS Noetic, catkin_tools and vcstool (no ROS installation needed)

GPU support

The image includes graphics support for new-generation Intel iGPUs (e.g. Meteor Lake, Intel Arc). Ubuntu 20.04's default graphics drivers are too old for these, so the image pulls Mesa 25.x from the kisak/turtle PPA and exposes the host's GPU (/dev/dri) to the container. No action needed — it's already set up.

Project Files

The stack is defined by two files next to this guide: docker-compose.yaml and Dockerfile.

docker-compose.yaml

services:
  auv-dev:
    build:
      context: ./
      dockerfile: ./Dockerfile
    image: auv-dev-image
    container_name: auv-dev
    environment:
      - DISPLAY=${DISPLAY}
      - QT_X11_NO_MITSHM=1
      - LIBGL_ALWAYS_SOFTWARE=0
      - MESA_LOADER_DRIVER_OVERRIDE=iris
    devices:
      - /dev/input/js0:/dev/input/js0
      - /dev/input:/dev/input
      - /dev/dri:/dev/dri
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
      - ./catkin_ws:/auv_ws:rw
    network_mode: host
    ipc: host
    privileged: true
    stdin_open: true
    tty: true
    command: /bin/zsh

• environment: forwards your display (DISPLAY) so GUI apps (rviz, gazebo) open on your screen; iris is the Mesa driver for new-generation Intel iGPUs.
• devices: /dev/dri gives the container your GPU, /dev/input lets it read joysticks.
• volumes: ./catkin_ws on your host is mounted at /auv_ws — the workspace persists on your machine, rebuilds are not lost.
• network_mode / ipc: host — the container shares the host's network (ROS works over localhost) and shared memory (needed for GUI).
• privileged / tty — full device access and an interactive shell (zsh).

Dockerfile (part by part)

Base image + core tools:

FROM osrf/ros:noetic-desktop-full

RUN --mount=type=cache,target=/var/cache/apt \
    --mount=type=cache,target=/var/lib/apt/lists \
    apt-get update && apt-get install -y --no-install-recommends \
    python3-vcstool \
    python3-catkin-tools \
    python3-pip \
    git \
    curl \
    wget \
    nano \
    software-properties-common

WORKDIR /auv_ws

osrf/ros:noetic-desktop-full already ships Ubuntu 20.04, ROS Noetic and Gazebo. The --mount=type=cache lines keep apt downloads cached between rebuilds, so rebuilding is fast.

ROS packages used by the AUV stack but not included in the package dependencies (rosdep):

RUN --mount=type=cache,target=/var/cache/apt \
    --mount=type=cache,target=/var/lib/apt/lists \
    apt-get update && \
    apt-get install -y --no-install-recommends \
    ros-noetic-vision-msgs \
    ros-noetic-ros-control \
    ros-noetic-ros-controllers \
    ros-noetic-robot-state-publisher \
    ros-noetic-joint-state-publisher \
    ros-noetic-joy \
    ros-noetic-xacro \
    ros-noetic-rosfmt \
    ros-noetic-smach-ros \
    ros-noetic-rosserial-python \
    ros-noetic-move-base \
    ros-noetic-pcl-ros \
    ros-noetic-pcl-conversions \
    ros-noetic-robot-localization

Python dependencies (PyTorch CPU, Ultralytics, image processing):

RUN --mount=type=cache,target=/root/.cache/pip pip3 install \
    "torch==1.8.0+cpu" \
    "torchvision==0.9.0+cpu" \
    "numpy<1.25.0" \
    "typing-extensions<4.6.0" \
    ultralytics \
    -f https://download.pytorch.org/whl/torch_stable.html
RUN --mount=type=cache,target=/root/.cache/pip pip3 install scikit-image

torch==1.8.0+cpu matches the Python 3.8 / Ubuntu 20.04 versions inside the container. The pip steps are separate because combining them made pip pick an incompatible networkx.

GPU support — this part is for new-generation Intel iGPUs (Meteor Lake, Intel Arc):

RUN --mount=type=cache,target=/var/cache/apt \
    --mount=type=cache,target=/var/lib/apt/lists \
    add-apt-repository -y ppa:kisak/turtle && \
    apt-get update && \
    apt-get install -y --no-install-recommends \
    mesa-utils \
    vainfo \
    mesa-va-drivers \
    libgl1-mesa-dri \
    libglx-mesa0 \
    libegl-mesa0 \
    libgbm1 \
    mesa-vulkan-drivers

Ubuntu 20.04 ships Mesa 20.x, which does not support new-generation Intel iGPUs. The kisak/turtle PPA backports Mesa 25.x to 20.04, giving OpenGL 4.6 + Vulkan on Meteor Lake/Arc.

Getting Started

Step 1: Start the Container

Start the container (and build the image on first run):

docker compose up -d --build

Enter the container shell (zsh):

docker compose exec auv-dev zsh

Your workspace lives at /auv_ws (mounted from ./catkin_ws on your host). catkin_ws lives on the host — you clone the repository on the host, and it's automatically synced into the container through the volume mount.

Step 2: Create Your Workspace

Create a catkin workspace on the host. Think of this as the home for all our ROS packages.

mkdir -p catkin_ws/src

Step 3: Clone the repository (on the host)

cd catkin_ws/src
git clone git@github.com:itu-auv/auv-software.git

The repo appears in the container at /auv_ws/src/auv-software automatically.

Step 4: Install build tools

Skip — catkin_tools and vcstool are already installed in the image.

Step 5: Initialize the Workspace

cd /auv_ws
catkin init

Step 6: Pull in third-party dependencies

Our project depends on several external packages (sensors, simulators, etc.). We manage these with .repos files:

# Import third-party packages (sensors, drivers, etc.)
vcs import src < src/auv-software/third_party.repos

# Import simulation packages (Gazebo worlds, UUV simulator, etc.)
vcs import src < src/auv-software/sim.repos

This will clone all the necessary repositories into your src folder.

Step 7: Install System Dependencies

ROS packages often need system libraries. Let's install them all at once using rosdep (you're root, so no sudo needed):

# rosdep is already initialized in the image; refresh the package lists
rosdep update

# Install all dependencies for packages in src/
rosdep install --from-paths src --ignore-src -r -y

Building the Workspace

cd /auv_ws
catkin build

This might take a few minutes on the first run. If no errors, you are ready to go.

Testing Your Workspace

Source the workspace (or just open a new terminal — it's sourced automatically):

source /auv_ws/devel/setup.bash   # or: source /auv_ws/devel/setup.zsh

Then start the simulation:

roslaunch auv_sim_bringup start_gazebo.launch

If Gazebo starts without errors, your setup is fully correct.

Still stuck? Ask the team!