From 7193a88ba7822f746abcfddfa5006f279ca16091 Mon Sep 17 00:00:00 2001 From: Alessio Lovato Date: Thu, 9 Jul 2026 16:18:35 +0200 Subject: [PATCH 1/2] Updated readmes --- README.md | 244 +++++++++++------------------------------------- jammy/README.md | 57 ++++++++--- noble/README.md | 78 +++++++++++++--- 3 files changed, 166 insertions(+), 213 deletions(-) diff --git a/README.md b/README.md index 6808416..bbefbf6 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,89 @@ -[![Build and Push (xbot2_docker-noble-ROS2)](https://github.com/ADVRHumanoids/xbot2_docker/actions/workflows/build-and-push-noble.yml/badge.svg)](https://github.com/ADVRHumanoids/xbot2_docker/actions/workflows/build-and-push-noble.yml) # XBot2 Docker - Robot Template Build System -This directory provides a generalized, reusable Docker build system for XBot2-based robots. It supports multiple ROS versions and different deployment configurations through a flexible, parameterized approach. +[![Build and Push (xbot2_docker-noble-ROS2)](https://github.com/ADVRHumanoids/xbot2_docker/actions/workflows/build-and-push-noble.yml/badge.svg)](https://github.com/ADVRHumanoids/xbot2_docker/actions/workflows/build-and-push-noble.yml) + +Docker images for XBot2 robotics framework, supporting multiple Ubuntu versions and ROS distributions. ## Overview -The robot-template build system is designed to create Docker images for any robot using the XBot2 framework. Instead of duplicating Dockerfiles for each robot, this system uses environment variables and build arguments to customize the build process for specific robots while maintaining a single set of build templates. +This repository provides Docker images and build configurations for running XBot2-based robots. Images are available for different Ubuntu versions (Focal, Jammy, Noble) with corresponding ROS distributions. ## Directory Structure ``` -robot-template/_build/ -├── robot-focal-ros1/ # ROS1 (Noetic on Ubuntu Focal) -│ ├── Dockerfile-base # Core development environment -│ ├── Dockerfile-xeno # Real-time Xenomai extension -│ ├── Dockerfile-locomotion # Locomotion control stack -│ ├── build.bash # Main build orchestrator -│ ├── compose.yml # Docker Compose for building -│ ├── compose.pull.yml # Docker Compose for pulling -│ └── scripts/ # Build and environment scripts -│ ├── build-base.bash # Base software installation -│ ├── build-xeno.bash # Xenomai-specific builds -│ └── env.bash # Runtime environment setup -└── robot-noble-ros2/ # ROS2 (Jazzy on Ubuntu Noble) - ├── Dockerfile-base # Core development environment - ├── Dockerfile-xeno # Real-time Xenomai extension - ├── Dockerfile-sim # Simulation environment - ├── build.bash # Main build orchestrator - ├── compose.yml # Docker Compose for building - └── scripts/ # Build and environment scripts +xbot2_docker/ +├── focal/ # Ubuntu 20.04 (Focal) - ROS1 Noetic +├── jammy/ # Ubuntu 22.04 (Jammy) - ROS2 Humble +└── noble/ # Ubuntu 24.04 (Noble) - ROS2 Jazzy ``` -## Build System Architecture +## Quick Start -The build system creates layered Docker images, each serving a specific purpose: +> [!NOTE] +> All the following commands are meant to be executed in the repo root directory or subfolder when specified by previous `cd` commands -### 1. Base Image -The foundation image includes: -- ROS installation (ROS1 Noetic or ROS2 Jazzy) -- XBot2 desktop full installation -- Development tools (git, vim, terminator, etc.) -- Python environment with required packages -- Robot-specific packages defined by environment variables +There are two ways to use XBot2 Docker images: -### 2. Xenomai Image (Real-time) -Extends the base image with: -- Xenomai real-time kernel support -- EtherCAT master capabilities -- Real-time device drivers -- Special user permissions for real-time operations +### Option 1: Pull Pre-built Images (Recommended) -### 3. Locomotion Image (ROS1) / Simulation Image (ROS2) -Specialized images containing: -- **ROS1**: Advanced locomotion control libraries (Horizon, Casadi, etc.) -- **ROS2**: MuJoCo simulation environment +If you **don't have access** to the xbot2 GitHub repositories, use pre-built images from the registry: -## Understanding the Build Process +```bash +cd noble/ # or focal/, jammy/ -### Environment Variables +# Pull the latest images +docker compose pull -The build system relies on environment variables to customize the build for specific robots. These must be set before running the build script: +# Start the container +docker compose up -d robot # For systems without NVIDIA GPU +docker compose up -d robot-nvidia # For systems with NVIDIA GPU +``` +Attach to the container: ```bash -# Robot identification -export ROBOT_NAME=myrobot # Used in paths and package names -export USER_NAME=user # Username inside containers -export USER_ID=1000 # Should match your host user ID -export KERNEL_VER=5 # Xenomai kernel version - -# Software configuration -export RECIPES_TAG=main # Git branch/tag for recipes -export RECIPES_REPO=git@github.com:advrhumanoids/multidof_recipes.git - -# Package selection -export ROBOT_PACKAGES="package1 package2" # Robot-specific packages -export ADDITIONAL_PACKAGES="sensor_driver" # Extra packages - -# Image naming -export BASE_IMAGE_NAME=myrobot-focal-ros1 # Base name for images -export TAGNAME=v1.0.0 # Version tag +docker compose exec robot terminator # or robot-nvidia ``` -### The build.bash Script +Stop the container: +```bash +docker compose down +``` -The main build script provides a unified interface for building, pulling, and pushing Docker images. Here's how to use it: +### Option 2: Build from Source -#### Basic Usage +If you have access to the xbot2 GitHub repositories and want to customize the build: ```bash -cd robot-focal-ros1/ # or robot-noble-ros2/ - -# Show help -./build.bash --help +cd noble/ # or focal/, jammy/ -# Build locally (default behavior) -./build.bash +# Build with custom configuration +./build.bash --recipes-repo https://github.com/advrhumanoids/multidof_recipes.git \ + --user-id $(id -u) \ + --recipes-tag ros2 \ + --forest-njobs 8 \ + --netrc ~/.netrc \ + --kernel-ver 5.10.172-xeno-ipipe-3.1 -# Build locally and push to registry -./build.bash --push +# Start the container +docker compose up -d -# Pull pre-built images from registry -./build.bash --pull +# Attach with terminator +docker compose exec dev terminator ``` -#### What Each Flag Does - -**`--local` (default)** -- Builds all images locally using Docker Compose -- Tags images with both local and registry names -- Does not push to registry -- Useful for development and testing - -**`--push`** -- Builds all images locally -- Tags images appropriately -- Pushes to the configured Docker registry -- Requires authentication to the registry - -**`--pull` or `--remote`** -- Downloads pre-built images from the registry -- Tags them for local use -- Faster than building from scratch -- Requires registry access - -### Build Flow Explained - -When you run `./build.bash`, the following sequence occurs: - -1. **Configuration Loading** - The script reads all environment variables and validates the configuration. If critical variables are missing, it will fail early with an error message. - -2. **Docker Compose Orchestration** - For local builds, the script uses `docker compose build`, which: - - Reads `compose.yml` to understand service dependencies - - Builds images in the correct order (base → xeno/locomotion) - - Passes environment variables as build arguments - - Mounts secrets (like `.netrc`) for private repository access - -3. **Multi-stage Building** - Each Dockerfile uses multi-stage builds: - ```dockerfile - FROM base_image - ARG USER_ID=1000 - # Install dependencies - RUN --mount=type=secret,id=netrc ... - ``` - This approach keeps images smaller and build secrets secure. - -4. **Image Tagging** - After building, images are tagged following this pattern: - - Local: `${BASE_IMAGE_NAME}-base` - - Registry: `hhcmhub/${BASE_IMAGE_NAME}-base:${TAGNAME}` - -5. **Optional Push** - If `--push` is specified, images are uploaded to the registry for team sharing. - -## Dockerfile Deep Dive - -### Base Dockerfile Structure - -Let's examine the key sections of `Dockerfile-base`: - -```dockerfile -FROM hhcmhub/xbot2-focal-dev:latest -# Uses official XBot2 development image as starting point - -ARG USER_ID=1000 -ARG ROBOT_NAME=robot -ARG RECIPES_TAG=main -# Build arguments allow customization - -USER root -RUN apt-get update && apt-get install -y \ - xbot2_desktop_full \ - ros-noetic-realsense2-camera -# System-wide package installation - -USER $USER_NAME -WORKDIR /home/$USER_NAME - -# Use mounted secrets for private repo access -RUN --mount=type=secret,id=netrc,uid=$USER_ID \ - /bin/bash scripts/build-base.bash -``` - -Key design decisions: -- Starts from official XBot2 base images -- Uses build arguments for flexibility -- Switches between root and user for appropriate permissions -- Leverages BuildKit secrets for secure private repo access - -### Build Scripts - -The `scripts/build-*.bash` files contain the actual software installation logic: - -**build-base.bash** -```bash -# Initialize forest workspace -mkdir xbot2_ws && cd xbot2_ws -forest init -source setup.bash - -# Add recipes repository with specified tag -forest add-recipes $RECIPES_REPO -t $RECIPES_TAG - -# Build core packages -forest grow xbot2_gui_server -forest grow xbot2_tools -j8 - -# Build robot-specific packages -for package in $ROBOT_PACKAGES; do - forest grow $package -j8 -v -done -``` +See version-specific READMEs for detailed instructions: +- [focal/README.md](focal/README.md) +- [jammy/README.md](jammy/README.md) +- [noble/README.md](noble/README.md) +## Available Images -This script: -- Sets up the forest build system -- Configures recipe repositories -- Builds packages in parallel where possible -- Cleans up build artifacts to reduce image size +| Image | Ubuntu | ROS | Description | +|-------|--------|-----|-------------| +| `xbot2-focal-dev` | 20.04 Focal | ROS1 Noetic | Development environment | +| `xbot2-jammy-dev` | 22.04 Jammy | ROS2 Humble | Development environment | +| `xbot2-noble-dev` | 24.04 Noble | ROS2 Jazzy | Development environment | +| `xbot2-noble-robot` | 24.04 Noble | ROS2 Jazzy | Robot-ready with core packages | +| `xbot2-noble-rt` | 24.04 Noble | ROS2 Jazzy | Real-time (RT) variant | +All images are hosted at `hhcmhub/` registry. diff --git a/jammy/README.md b/jammy/README.md index 1fcdfb4..b176ff9 100644 --- a/jammy/README.md +++ b/jammy/README.md @@ -1,33 +1,68 @@ -# Usage +# XBot2 Jammy (Ubuntu 22.04) - ROS2 Humble -## Build the container +This folder contains Docker configurations for XBot2 on Ubuntu 22.04 Jammy with ROS2 Humble. + +## Quick Start + +### Option 1: Pull Pre-built Images (Recommended) + +If you **don't have access** to the xbot2 GitHub repositories, you can pull and use pre-built images: + +```bash +# Pull the latest images +docker compose pull + +# Start the container with NVIDIA GPU support +docker compose up -d +``` + +Attach to the running container: +```bash +docker compose exec dev terminator +``` + +Stop the container: +```bash +docker compose down +``` + +### Option 2: Build from Source + +If you have access to xbot2 GitHub repositories and want to build locally: + +#### Build the container ```bash USER_ID=$(id -u) docker compose build ``` -If your user id is 1000 (very common), you can drop the first part. -## Start the container +If your user ID is 1000 (very common), you can omit the `USER_ID` part: +```bash +docker compose build +``` + +#### Start the container ```bash docker compose up -d ``` -## Attach with terminator +#### Attach with terminator ```bash docker compose exec dev terminator ``` -## Build the whole forest workspace +#### Build the whole forest workspace +Inside the container: ```bash -docker compose exec dev terminator ./bootstrap.sh ``` -## Stop the container +#### Stop the container ```bash docker compose down ``` -## Troubleshooting +## Image Details + +The image is pulled from `hhcmhub/` registry: +- `hhcmhub/xbot2-jammy-dev:latest` - Development environment with ROS2 Humble -### Permission problems when running GUI tools -Maybe you're not running with nVidia GPU. You need to run `xhost local:root`. diff --git a/noble/README.md b/noble/README.md index 59b3110..8153317 100644 --- a/noble/README.md +++ b/noble/README.md @@ -1,33 +1,85 @@ -# Usage +# XBot2 Noble (Ubuntu 24.04) - ROS2 Jazzy + +This folder contains Docker configurations for XBot2 on Ubuntu 24.04 Noble with ROS2 Jazzy. + +## Quick Start + +### Option 1: Pull Pre-built Images (Recommended) + +If you **don't have access** to the xbot2 GitHub repositories, use pre-built images: -## Build the container -Example: ```bash -./build.bash --recipes-repo https://github.com/advrhumanoids/multidof_recipes.git --user-id 1000 --recipes-tag ros2 --forest-njobs 8 --netrc ~/.netrc +# Pull the latest images +docker compose pull + +# Start the container +docker compose up -d robot # For systems WITHOUT NVIDIA GPU +docker compose up -d robot-nvidia # For systems WITH NVIDIA GPU ``` -## Start the container +Attach to the running container: ```bash -docker compose up -d +docker compose exec robot terminator # or robot-nvidia ``` -## Attach with terminator +Stop the container: ```bash -docker compose exec dev terminator +docker compose down +``` + +### Option 2: Build from Source + +If you have access to xbot2 GitHub repositories and want to build locally: + +#### Build the container +```bash +./build.bash --recipes-repo https://github.com/advrhumanoids/multidof_recipes.git \ + --user-id $(id -u) \ + --recipes-tag ros2 \ + --forest-njobs 8 \ + --netrc ~/.netrc +``` + +#### Start the dev container +```bash +docker compose up -d dev # Without NVIDIA GPU +docker compose up -d dev-nvidia # With NVIDIA GPU ``` -## Build the whole forest workspace +#### Attach with terminator ```bash docker compose exec dev terminator -./bootstrap.sh ``` -## Stop the container +#### Stop the container ```bash docker compose down ``` +## Available Services + +The `compose.yaml` file defines several services: + +| Service | Image | GPU Support | Use Case | +|---------|-------|-------------|----------| +| `dev` | `xbot2-noble-dev` | No | Development, building from source | +| `dev-nvidia` | `xbot2-noble-dev` | Yes | Development with GPU | +| `robot` | `xbot2-noble-robot` | No | Pre-built robot image | +| `robot-nvidia` | `xbot2-noble-robot` | Yes | Pre-built robot image with GPU | +| `rt` | `xbot2-noble-rt` | No | Real-time variant | + ## Troubleshooting -### Permission problems when running GUI tools -Maybe you're not running with nVidia GPU. You need to run `xhost local:root`. + +### Choosing the Right Service + +- **robot / robot-nvidia**: Usually this is the way to go since is the version you'll find also in the robot. +- **dev / dev-nvidia**: Use these if you need to build packages from source or customize the installation. +- **rt**: Use this for real-time kernel support (advanced use case). + +## Image Details + +All images are pulled from `hhcmhub/` registry: +- `hhcmhub/xbot2-noble-dev:latest` - Base development environment +- `hhcmhub/xbot2-noble-robot:latest` - Robot-ready with core packages +- `hhcmhub/xbot2-noble-rt:latest` - Real-time kernel variant From b4a5fed2941f27917cd1312854693041133fee44 Mon Sep 17 00:00:00 2001 From: Alessio Lovato Date: Thu, 9 Jul 2026 16:20:33 +0200 Subject: [PATCH 2/2] Updated notice --- README.md | 2 +- jammy/README.md | 3 +++ noble/README.md | 3 +++ 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bbefbf6..1de0900 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ xbot2_docker/ ## Quick Start > [!NOTE] -> All the following commands are meant to be executed in the repo root directory or subfolder when specified by previous `cd` commands +> All the following commands are meant to be executed in each subfolder, as pointed aout from the `cd` command in the example. There are two ways to use XBot2 Docker images: diff --git a/jammy/README.md b/jammy/README.md index b176ff9..43a443b 100644 --- a/jammy/README.md +++ b/jammy/README.md @@ -4,6 +4,9 @@ This folder contains Docker configurations for XBot2 on Ubuntu 22.04 Jammy with ## Quick Start +> [!NOTE] +> All the following commands are meant to be executed in this folder. + ### Option 1: Pull Pre-built Images (Recommended) If you **don't have access** to the xbot2 GitHub repositories, you can pull and use pre-built images: diff --git a/noble/README.md b/noble/README.md index 8153317..66547bb 100644 --- a/noble/README.md +++ b/noble/README.md @@ -4,6 +4,9 @@ This folder contains Docker configurations for XBot2 on Ubuntu 24.04 Noble with ## Quick Start +> [!NOTE] +> All the following commands are meant to be executed in this folder. + ### Option 1: Pull Pre-built Images (Recommended) If you **don't have access** to the xbot2 GitHub repositories, use pre-built images: