A sophisticated, multi-layer Docker-based development environment for ROS2 projects with intelligent caching, automated dependency management, and seamless developer experience.

# Clone and setup
git clone <your-repo>
cd <your-repo>
git submodule update --init --recursive

# Build the complete environment
make build

# Start developing
make cli

• Base Foundation: Ubuntu 24.04 + ROS2 Jazzy core (highly cacheable, user-agnostic)
• Core Environment: Complete toolchain + all discovered dependencies (shareable across users)
• User Layer: Personal customization + .deb packages + user account (user-specific)

• Intelligent Caching: Only rebuilds changed layers using SHA256 fingerprinting
• Requirements Discovery: Automatically finds and installs from .system, .pip3, .ppa files
• Package Management: Installs custom .deb packages from vendor/ directory
• Cross-Platform: Native ARM64 and x86_64 support with cross-compilation
• Registry Integration: Pull/push layer caching for CI/CD optimization

• Interactive CLI: Seamless container attach/detach with persistent state
• Hot Reloading: Live code mounting for immediate development feedback
• Shell Integration: zsh with oh-my-zsh and custom ADORe CLI prompt
• History Persistence: Command history preserved across sessions
• Change Detection: Automatically detects requirement and package changes

┌─────────────────────────────────────────────────────────────┐
│                    ADORe CLI Architecture                    │
├─────────────────────────────────────────────────────────────┤
│  User Layer (adore_cli:tag)                                 │
│  ├─ User account & shell environment                        │
│  ├─ .deb packages from vendor/                              │
│  ├─ Personal development tools                              │
│  └─ Final development-ready image                           │
├─────────────────────────────────────────────────────────────┤
│  Core Environment (adore_cli_core:tag)                      │
│  ├─ All project requirements (.system, .pip3, .ppa)        │
│  ├─ ROS2 complete toolchain and build tools                 │
│  ├─ Development libraries and dependencies                  │
│  └─ User-agnostic shareable environment                     │
├─────────────────────────────────────────────────────────────┤
│  Base Foundation (adore_cli_base:tag)                       │
│  ├─ Ubuntu 24.04 Noble + ROS2 Jazzy foundation             │
│  ├─ System fundamentals and container runtime              │
│  ├─ Oh-my-zsh and shell configuration                       │
│  └─ Highly cacheable, globally shareable                    │
└─────────────────────────────────────────────────────────────┘

• Docker: 28.0+ with BuildKit support
• OS: Linux (Ubuntu 20.04+ recommended)
• Memory: 8GB+ RAM, 20GB+ free disk space
• Make: GNU Make for build orchestration
• Git: For submodule management

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Make
sudo apt update && sudo apt install make git

# Logout and login to apply Docker group membership

# Start development session
make cli

# Inside container - your code is mounted at /tmp/adore
cd /tmp/adore

# Build your ROS2 packages
colcon build

# Run your code
ros2 launch my_package my_launch.py

# Exit (container keeps running)
exit

# Reattach to same session
make cli

# Stop when done
make stop

ADORe CLI automatically discovers and installs dependencies from your project:

• requirements.system or *.system: APT package requirements
• requirements.pip3 or *.pip3: Python package requirements
• requirements.ppa or *.ppa: Ubuntu PPA repositories

requirements.system:

ros-jazzy-rclcpp
vim
git
cmake
build-essential

requirements.pip3:

numpy
matplotlib
rosdep
colcon-common-extensions

requirements.ppa:

ppa:deadsnakes/ppa

Place .deb files in vendor/ directory for automatic installation:

vendor/
├── my-custom-lib_1.0.0_amd64.deb
├── another-package_2.1.0_amd64.deb
└── subdirectory/
    └── nested-package_1.5.0_amd64.deb

# Force complete rebuild (ignores cache)
make rebuild_force

# Rebuild from specific layer
make rebuild_from_layer LAYER=base    # Rebuild all layers
make rebuild_from_layer LAYER=core    # Rebuild core + user
make rebuild_from_layer LAYER=user    # Rebuild user only

# Check build status
make build_status

# Show configuration
make adore_cli_info

# Architecture selection
export ARCH=amd64  # or arm64

# ROS Distribution
export ROS_DISTRO=jazzy

# Custom hostname
export HOSTNAME=my-dev-environment

# Set repository for registry operations
export GITHUB_REPOSITORY=your-org/your-repo

# Pull base/core images from registry
make try_pull_base_images

# Push base/core images to registry
make push_base_images

# Check registry status
make registry_status

ADORe CLI supports automated builds and registry integration:

The project includes reusable workflows:

• Native x86_64 builds: ubuntu-latest runners
• Native ARM64 builds: ubuntu-24.04-arm runners
• Cross-compilation: x86_64 to ARM64
• Registry push: Automatic base/core layer sharing

• Runs on all branches and pull requests
• Pushes base images only from origin repository (not forks)
• Intelligent caching using registry layers
• Parallel builds for different architectures
• Comprehensive logging and artifact uploads

Environment Changes Detected:

# Check what changed
make show_changes

# Rebuild affected layers
make rebuild_from_layer LAYER=core  # For requirements changes
make rebuild_from_layer LAYER=user  # For .deb package changes

Build Failures:

# Check Docker status
docker info

# Clean Docker cache
docker system prune -f

# Force complete rebuild
make rebuild_force

Container Issues:

# Debug container interactively
make debug_run

# Debug as root
make debug_run_root

# Check container logs
docker logs adore_cli_<tag>

# Show detailed configuration
make adore_cli_info

# Debug requirements processing
cd adore_cli_core && make debug_requirements

# Debug package installation
cd adore_cli && make debug_packages

# Test ROS2 installation
make test_ros2_installation

ADORe CLI uses sophisticated tagging based on multiple factors:

• Base Layer: adore_cli_base:<arch>_<branch>_<hash>
• Core Layer: adore_cli_core:<arch>_<branch>_<hash>_RH<requirements_hash>
• User Layer: adore_cli:<arch>_<branch>_<hash>_PH<packages_hash>_<user>_UID<uid>GID<gid>

The system automatically detects changes and rebuilds only necessary layers:

• Base: Rebuilds when ADORe CLI code changes
• Core: Rebuilds when requirements files change
• User: Rebuilds when .deb packages change

• Base/Core layers: Shared across users and environments
• User layers: Never pushed (user-specific)
• CI/CD optimization: Pull cached layers before building
• Security: Only origin repository can push images

# Clone for development
git clone <adore-cli-repo>
cd adore-cli
git submodule update --init --recursive

# Test changes
make build
make cli

1. Add Requirements: Place new .system, .pip3, or .ppa files in your project
2. Add Packages: Place .deb files in vendor/ directory
3. Test: Run make rebuild_from_layer LAYER=core or LAYER=user
4. Verify: Use make cli to test the new environment

This project is licensed under the Eclipse Public License - v 2.0 - see the LICENSE file for details.

Made with ❤️ for the ROS2 development community