Skip to content

Updated READMES #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlessioLovato wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Updated READMES #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7193a88
Updated readmes
AlessioLovato Jul 9, 2026
b4a5fed
Updated notice
AlessioLovato Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 55 additions & 189 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 each subfolder, as pointed aout from the `cd` command in the example.

### 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.
60 changes: 49 additions & 11 deletions jammy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,71 @@
# Usage
# XBot2 Jammy (Ubuntu 22.04) - ROS2 Humble

This folder contains Docker configurations for XBot2 on Ubuntu 22.04 Jammy with ROS2 Humble.

## 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:

## Build the container
```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`.
Loading