Ansible Playbooks for ROS 2 Setup#

The project has been migrated from shell scripts to Ansible playbooks for all the aspects of robot and dev machine setup.

Directory Structure#

The Ansible playbooks are located in the ansible directory:

ansible/
├── ansible-virtual.cfg          # Configuration for virtual bots
├── ansible.cfg                  # Ansible configuration
├── inventories/                 # Inventory files for different environments
│   ├── localhost.yml            # Local machine inventory
│   ├── real-robots.yml          # Real robot inventory
│   └── virtual-bots.yml         # Docker-based virtual bots inventory
├── playbooks/                   # Playbooks for different tasks
│   ├── 0_start_virtual_bots.yml # Start Docker containers for virtual bots
│   ├── 1_pam_ssh_agent_auth.yml # SSH agent authentication setup
│   ├── 10_install_docker.yml    # Docker installation
│   ├── 20_ros_setup.yml         # Main ROS 2 setup playbook
│   ├── 100_startup_service.yml  # Robot startup service
│   ├── 200_pair_controller.yml  # Controller pairing
│   ├── 9999_stop_virtual_bots.yml # Stop Docker containers for virtual bots
│   ├── group_vars/              # Playbook-specific variables
│   │   └── all.yml              # Configuration variables
│   ├── roles/                   # Individual roles for each component
│   │   ├── basic_prereqs/       # Basic prerequisites
│   │   ├── clang/               # Clang installation
│   │   ├── cmake/               # CMake installation
│   │   ├── colcon_setup/        # Colcon mixin setup
│   │   ├── dev_tools/           # Development tools
│   │   ├── extra_facts/         # System facts gathering
│   │   ├── locale_setup/        # UTF-8 locale setup
│   │   ├── utc_timezone/        # UTC timezone setup
│   │   ├── nodejs/              # Node.js and NPM
│   │   ├── ros_dependencies/    # ROS dependencies (uses known packages)
│   │   ├── ros_install_prebuilt/ # ROS 2 installation from packages
│   │   ├── ros_install_source/  # ROS 2 installation from source
│   │   └── ros_user_setup/      # ROS user creation and setup
│   └── test_ros_dependencies.yml # Test playbook for ROS dependencies
└── README.md                    # Points back to this documentation

Configuration#

Edit ansible/playbooks/group_vars/all.yml to configure:

  • ros_distro: ROS 2 distribution (default: jazzy)

  • source_install: Whether to install ROS 2 from source (default: false)

  • clang_version: Clang version to install (default: 20)

  • ci_mode: Whether running in CI environment (default: false)

Usage#

Quick Start#

To set up a ROS 2 development environment:

cd ansible
./setup-ros.sh

Install ROS 2 from packages (default)#

ansible-playbook playbooks/20_ros_setup.yml

Install ROS 2 from source#

ansible-playbook playbooks/20_ros_setup.yml -e "source_install=true"

Run specific roles only#

ansible-playbook playbooks/20_ros_setup.yml --tags "basic_prereqs,cmake"

Available role tags:

  • extra_facts: System facts gathering (always runs)

  • basic_prereqs: Basic prerequisites

  • locale_setup: UTF-8 locale setup

  • utc_timezone: UTC timezone setup

  • cmake_kitware: CMake installation from Kitware repository

  • cmake_system: CMake installation from system packages

  • dev_tools: Development tools

  • colcon_setup: Colcon mixin setup

  • fish_setup: Fish shell configuration for ROS 2

  • ros_install_prebuilt: ROS 2 installation from packages

  • ros_install_source: ROS 2 installation from source

  • ros_dependencies: ROS dependencies

  • nodejs: Node.js and NPM

  • clang: Clang installation

  • ros_user_setup: ROS user creation and setup

Run only the ROS installation part#

For prebuilt packages:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_install_prebuilt"

For source installation:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_install_source" -e "source_install=true"

You can also use the combined tag:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_install"

This will run either ros_install_prebuilt or ros_install_source based on the source_install variable.

Using specific inventory#

For real robots:

ansible-playbook -i inventories/real-robots.yml playbooks/20_ros_setup.yml

For local machine:

ansible-playbook -i inventories/localhost.yml playbooks/20_ros_setup.yml

For Docker-based virtual bots:

# First start the virtual bots
env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook playbooks/0_start_virtual_bots.yml

# Then run the setup playbook
env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook playbooks/20_ros_setup.yml

# When finished, stop the virtual bots
env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook playbooks/9999_stop_virtual_bots.yml

For faster iteration, playbooks can be chained:

env ANSIBLE_CONFIG=ansible-virtual.cfg ansible-playbook \
    playbooks/9999_stop_virtual_bots.yml \
    playbooks/0_start_virtual_bots.yml \
    playbooks/20_ros_setup.yml -vvv

Generating ROS Dependencies#

The project includes a script to generate ROS dependencies based on your project:

./scripts/ros-dep-gen-ansible.sh

This script:

  1. Analyzes the project’s ROS dependencies using rosdep

  2. Generates a variables file in ansible/playbooks/roles/ros_dependencies/vars/known_ros_dependencies.yml

  3. The generated variables (ros_dependencies_known_packages) are automatically used by the ros_dependencies role

To run only the ROS dependencies role:

ansible-playbook playbooks/20_ros_setup.yml --tags "ros_dependencies"

Alternatively, you can use the dedicated test playbook:

ansible-playbook playbooks/test_ros_dependencies.yml

Requirements#

  • Ubuntu 22.04 or newer

  • Ansible 2.9 or newer

  • Required Ansible collections:

    ansible-galaxy collection install community.general

Post-Installation Notes#

After installation, you may need to add Clang to your PATH:

For fish (in ~/.config/fish/config.fish):

set -gx PATH /usr/lib/llvm-20/bin $PATH

For bash (in ~/.bashrc):

export PATH="/usr/lib/llvm-20/bin:$PATH"

For dockerfile:

ENV PATH="/usr/lib/llvm-20/bin:$PATH"

Docker Integration#

The project includes Ansible playbooks for Docker integration:

Installing Docker#

To install Docker on robots:

ansible-playbook -i inventories/real-robots.yml playbooks/10_install_docker.yml

This playbook:

  • Installs Docker Engine and related tools

  • Configures Docker daemon with proper logging settings

  • Adds the user to the Docker group for non-root access

Robot Startup Service#

The project includes a playbook to set up a systemd service that runs ROS nodes in Docker containers:

ansible-playbook -i inventories/real-robots.yml playbooks/100_startup_service.yml

This playbook:

  • Pulls the latest Docker image from GitHub Container Registry

  • Creates two systemd services:

    • drqp-control-service: Runs the main control nodes

    • drqp-joystick-service: Runs the joystick node with hot-plugging support

SSH Agent Authentication#

To enable passwordless sudo using SSH agent authentication:

ansible-playbook -i inventories/real-robots.yml playbooks/1_pam_ssh_agent_auth.yml

This playbook:

  • Installs libpam-ssh-agent-auth package

  • Configures PAM to allow sudo authentication via SSH agent

  • Adds your SSH public key to the authorized keys file

Controller Pairing#

To pair a DualSense wireless controller with a robot:

ansible-playbook -i inventories/real-robots.yml playbooks/200_pair_controller.yml -e "controller_name=DualSense"

or

ansible-playbook -i inventories/real-robots.yml playbooks/200_pair_controller.yml -e "controller_mac=XX:XX:XX:XX:XX:XX"

Migration from Shell Scripts#

The Ansible playbooks replace the following shell scripts:

  • scripts/ros/ros-2-prep.sh → ansible/playbooks/20_ros_setup.yml

  • scripts/ros/ros-2-src-build.sh → ansible/playbooks/roles/ros_install_source

  • scripts/ros/__gen_install_ros_dependencies.sh → ansible/playbooks/roles/ros_dependencies with known packages

  • scripts/install_docker.sh → ansible/playbooks/10_install_docker.yml

  • scripts/ros/desktop/ros-desktop.dockerfile (user setup) → ansible/playbooks/roles/ros_user_setup

  • scripts/ros/fish/setup.fish → ansible/playbooks/roles/fish_setup

  • scripts/ros/colcon-mixin.sh → ansible/playbooks/roles/colcon_setup

  • scripts/ros/rosdep-update.sh → ansible/playbooks/roles/colcon_setup

Benefits

The Ansible playbooks provide several advantages:

  • Better organization with roles for each component

  • Idempotency (can be run multiple times without issues)

  • Selective execution with tags

  • Better error handling

  • Configurable variables

  • Better documentation

  • Docker integration for containerized deployment

  • Support for virtual bots for testing

  • Improved SSH authentication

  • Controller pairing automation