• Stars
    star
    520
  • Rank 82,955 (Top 2 %)
  • Language
    Python
  • License
    Apache License 2.0
  • Created over 5 years ago
  • Updated 10 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A tool to run docker containers with overlays and convenient options for things like GUIs etc.

rocker

A tool to run docker images with customized local support injected for things like nvidia support. And user id specific files for cleaner mounting file permissions.

Difference from docker-compose

A common question about rocker is how is it different than docker-compose. rocker is designed to solve a similar but different problem than docker-compose. The primary goal of rocker is to support the use of Docker in use cases where the containers will be effected by the local environment. A primary example of this is setting up file permissions inside the container to match the users outside of the container so that mounted files inside the container have the same UID as the host. Doing this enables quickly going in and out of different containrs while leverating the same workspace on your host for testing on different platforms etc. This is done by dynamically generating overlays on the same core image after detecting the local conditions required.

The secondary feature that rocker provides that docker-compose does not address is the ability to inject extra use case specific capabilities into a container before running. A common example is the ability to use NVIDIA drivers on a standard published image. rocker will take that standard published image and both inject the necessary drivers into the container which will match your host driver and simultaneously set the correct runtime flags. This is possible to do with docker-compose or straight docker. But the drawbacks are that you have to build and publish the combinatoric images of all possible drivers, and in addition you need to manually make sure to pass all the correct runtime arguments. This is especially true if you want to combine multiple possible additional features, such that the number of images starts scaling in a polynomic manner and maintenance of the number of images becomes unmanagable quickly. Whereas with rocker you can invoke your specific plugins and it will use multi-stage builds of docker images to customize the container for your specific use case, which lets you use official upstream docker images without requiring you to maintain a plethora of parallel built images.

Know extensions

Rocker supports extensions via entry points there are some built in but you can add your own.

Integrated Extensions

There are a number of integrated extensions here's some of the highlights. You can get full details on the extensions from the main rocker --help command.

  • x11 -- Enable the use of X11 inside the container via the host X instance.
  • nvidia -- Enable NVIDIA graphics cards for rendering
  • cuda -- Enable NVIDIA CUDA in the container
  • user -- Create a user inside the container with the same settings as the host and run commands inside the container as that user.
  • home -- Mount the user's home directory into the container
  • pulse -- Mount pulse audio into the container
  • ssh -- Pass through ssh access to the container.

As well as access to many of the docker arguments as well such as device, env, volume, name, network, and privileged.

Externally maintained extensions

Here's a list of public repositories with extensions.

Prerequisites

This should work on most systems using with a recent docker version available.

Docker installation instructions: https://docs.docker.com/install/

NVIDIA settings

For the NVIDIA option this has been tested on the following systems using nvidia docker2:

Ubuntu distribution Linux Kernel Nvidia drivers
16.04 4.15 nvidia-384 (works)
nvidia-340 (doesn't work)
18.04 nvidia-390 (works)
20.04 5.4.0 nvidia-driver-460 (works)
22.04 5.13.0 nvidia-driver-470 (works)

Install nvidia-docker 2: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker

Additional Configuration for rootless mode

For executing Docker as a non-root user, separate installation instructions are provided here: https://docs.docker.com/engine/security/rootless/

After installing Rootless Docker, the nvidia-docker2 package can be installed as usual from the website above. Currently, cgroups are not supported in rootless mode so we need to change no-cgroups in /etc/nvidia-container-runtime/config.toml

[nvidia-container-cli]
no-cgroups = true

Note, that changing this setting will lead to a Failed to initialize NVML: Unknown Error if Docker is executed as root (noted here).

Intel integrated graphics support

For Intel integrated graphics support you will need to mount the /dev/dri directory as follows:

--devices /dev/dri

Installation

Debians (Recommended)

Debian packages are available from the ROS repositories. You can set them up in step one here then come back.

Then you can sudo apt-get install python3-rocker

PIP

If you're not on a Ubuntu or Debian platform.

Rocker is available via pip you can install it via pip using

pip install rocker

Archlinux (AUR)

Using any AUR helper, for example, with paru

paru -S python-rocker

or

paru -S python-rocker-git

Development

To set things up in a virtual environment for isolation is a good way. If you don't already have it install python3's venv module.

sudo apt-get install python3-venv

Create a venv

mkdir -p ~/rocker_venv
python3 -m venv ~/rocker_venv

Install rocker

cd ~/rocker_venv
. ~/rocker_venv/bin/activate
pip install git+https://github.com/osrf/rocker.git

For any new terminal re activate the venv before trying to use it.

. ~/rocker_venv/bin/activate

Testing

To run tests install the 'test' extra and pytest-cov in the venv

. ~/rocker_venv/bin/activate
pip install -e .[test] pytest-cov

Then you can run pytest.

python3 -m pytest --cov=rocker

Notes:

  • Make sure to use the python3 instance of pytest from inside the environment.
  • The tests include an nvidia test which assumes you're using a machine with an nvidia gpu.

Example usage

Fly a drone

Example usage with an iris

rocker --nvidia --x11 --user --home --pull --pulse tfoote/drone_demo

After the ekf converges,

You can send a takeoff command and then click to command the vehicle to fly to a point on the map.

Fly a plane

Example usage with a plane

rocker --nvidia --x11 --user --home --pull --pulse tfoote/drone_demo roslaunch sitl_launcher plane_demo.launch world_name:=worlds/plane.world gui:=false

In QGroundControl go ahead and make a mission, upload it, and then start the mission.

ROS 2 rviz

rocker --nvidia --x11 osrf/ros:crystal-desktop rviz2

Generic gazebo

On Xenial

rocker --nvidia --x11 osrf/ros:kinetic-desktop-full gazebo

On Bionic

rocker --nvidia --x11 osrf/ros:melodic-desktop-full gazebo

Volume mount

For arguments with one element not colon separated

--volume adds paths as docker volumes.

The last path must be terminated with two dashes --.

rocker --volume ~/.vimrc ~/.bashrc -- ubuntu:18.04

The above example of the volume option will be expanded via absolute paths for docker run as follows:

--volume /home/<USERNAME>/.vimrc:/home/<USERNAME>/.vimrc --volume /home/<USERNAME>/.bashrc:/home/<USERNAME>/.bashrc  

For arguments with colon separation

It will process the same as docker's --volume option, rocker --volume takes 3 fields.

  • 1st field: the path to the file or directory on the host machine.
  • 2nd field: (optional) the path where the file or directory is mounted in the container.
    • If only the 1st field is supplied, same value as the 1st field will be populated as the 2nd field.
  • 3rd field: (optional) bind propagation as ro, z, and Z. See docs.docker.com for further detail.

More Repositories

1

gazebo_models

Gazebo database of SDF models. This is a predecessor to https://app.gazebosim.org
HTML
799
star
2

car_demo

C++
496
star
3

rosbook

Example code to accompany the book Programming Robots with ROS
Python
473
star
4

docker_images

A repository to hold definitions of docker images maintained by OSRF
Dockerfile
457
star
5

vrx

Virtual RobotX (VRX) resources.
C++
381
star
6

subt

This repostory contains software for the virtual track of the DARPA SubT Challenge. Within this repository you will find Gazebo simulation assets, ROS interfaces, support scripts and plugins, and documentation needed to compete in the SubT Virtual Challenge.
C++
288
star
7

rvizweb

RVizWeb: RViz on the browser
HTML
275
star
8

icra2023_ros2_gz_tutorial

ICRA 2023 tutorial on ROS 2 and the new Gazebo (MT28, ICC Capital Suite 14)
Dockerfile
225
star
9

subt_hello_world

Hello World for DARPA SubT Challenge
C++
199
star
10

ovc

the Open Vision Computer
C
196
star
11

gazebo_tutorials

Tutorials for gazebo
C++
141
star
12

ros2multirobotbook

TypeScript
110
star
13

rmf_core

Provides the centralized functions of RMF: scheduling, etc.
C++
102
star
14

tensorflow_object_detector

Tensorflow Object Detector
Jupyter Notebook
97
star
15

autodock

ROS packages for automatic docking
Python
74
star
16

rmf_demos

Demos to showcase the capabilities of RMF
C++
70
star
17

osrf_wiki

69
star
18

mbzirc

Simulator for the MBZIRC Maritime Grand Challenge
C++
64
star
19

gzweb

Web client for Gazebo classic simulation
JavaScript
62
star
20

citysim

Example city simulation for autonomous vehicles in Gazebo Classic.
HTML
61
star
21

ros2_serial_example

C
59
star
22

rosbag_direct_write

C++ API for (potentially) faster writing of rosbag's using O_DIRECT with memory alignment.
C++
59
star
23

lrauv

Packages for simulating the Tethys-class Long-Range AUV (LRAUV) from the Monterey Bay Aquarium Research Institute (MBARI).
C++
54
star
24

homebrew-simulation

Homebrew tap for osrf simulation software
Ruby
49
star
25

vehicle_gateway

A pluginlib-based C++ library that interfaces with several vehicle SDK's
C++
42
star
26

vorc

Virtual Ocean Robot Challenge (VORC) resources
Python
39
star
27

ros_dds

(Deprecated) Prototype system using DDS as the middleware for a ROS like API.
C++
37
star
28

drone_demo

C++
36
star
29

osrf_testing_tools_cpp

Common testing tools for C++ which are used for testing in various OSRF projects.
C++
32
star
30

baxter_demos

Demos showing the functionality of the Baxter Research Robot.
Python
29
star
31

gazebo_osm

OpenStreetMap support for Gazebo
Python
28
star
32

dynamic_message_introspection

C++
27
star
33

uctf

Unmanned Capture the Flag (U-CTF) project.
Python
24
star
34

ros2_raw_dds_example

A project showing how to connect a raw DDS program to a ROS 2 graph
C++
23
star
35

yolo_object_detector

Object detector in ROS using deep learning in Darknet - Yolo
C
22
star
36

TSC-RMW-Reports

ROS 2 Middleware evaluation reports for each ROS release
Jupyter Notebook
22
star
37

nodelet_rosbag

C++
20
star
38

robocup_3d_simulation

A repository for Gazebo and ROS based robocup_3d_simulation.
C++
19
star
39

uav_testing

A collection of worlds for UAV testing
CMake
18
star
40

mbari_wec_gz

Simulation of wave energy harvesting buoy
C++
16
star
41

bzip2_cmake

libbz2 built with cmake
C
16
star
42

ros2_test_cases

Tracking of tests to be performed on a ROS 2 release
16
star
43

rviz_aerial_plugins

C++
15
star
44

www.ros.org

Old design work for new www.ros.org website
PHP
15
star
45

drcsim

Repository for the DRC project.
C++
14
star
46

multiarch-docker-image-generation

Shell
13
star
47

mbari_wec

Entrypoint to wave harvesting buoy
Dockerfile
13
star
48

docker_templates

EmberScript
13
star
49

negotiated

C++
12
star
50

robocup3ds

Gazebo support for the RoboCup 3D simulation league.
C++
11
star
51

servicesim

Service Robot Simulator
HTML
11
star
52

nexus

Core packages of Nexus
C++
10
star
53

ariac-docker

Containerization of ARIAC competition server and competitors' code. See https://bitbucket.org/osrf/ariac/wiki/Home
Shell
10
star
54

srcsim

Space Robotics Challenge
C++
9
star
55

wandrr

Firmware and electronics for the WANDRR robot
C
8
star
56

collaboration

Repo for collaborating on documents
Jupyter Notebook
8
star
57

capabilities

Implements the concept of capabilities as part of the robots-in-concert system.
Python
8
star
58

mir100-client

Generated from mir100 rest api pdf
Python
7
star
59

osrf_pycommon

Commonly needed Python modules, used by Python software developed at OSRF
Python
7
star
60

rosprofiler

The rosprofiler package
Python
7
star
61

system_data_recorder

A rosbag2 recorder node that backs up split files to an external location during recording
C++
7
star
62

py3-ready

Tools for checking if code is ready for python3
Python
7
star
63

rqt_graphprofiler

An experimental visualization system for anonymous publish subscribe architectures.
Python
7
star
64

rmf_schedule_visualizer

Visualizer for trajectories in the rmf schedule database
C++
6
star
65

ros2-porting-heuristics

Scripts to estimate the amount of work needed to port a package to ROS 2.
Python
6
star
66

osrf_hw

HTML
6
star
67

disc_zmq

Simple library (with implementations in languages of interest) to do discovery on top of zeromq messaging. The intent is that this library would be incorporated into other projects, where things like message serialization would be added.
C++
6
star
68

vrx-docker

Containerization of VRX competition server and competitors' code. See https://bitbucket.org/osrf/vrx/wiki/Home
Shell
5
star
69

auto-abi-checker

Tool designed to facilitate the run the great ABI compliance checker by supporting easy inputs and no configuration files
C++
5
star
70

ros2_ign

Integration between ROS 2 and Ignition
C++
5
star
71

gsoc-ros-neural

Repository for the GSOC 2015 Neural Interfaces for ROS project, sponsored by OSRF.
Python
5
star
72

collision_map_creator_plugin

HTML
4
star
73

infrastructure

Repository for tracking issues across Open Robotics infrastructure
4
star
74

slow_bldc

C
4
star
75

mesh_to_sdf

Shell
4
star
76

gazebo-doc-index

A platform that brings together all of Gazebo's learning resources in one place, in an organised fashion, helping beginners and professionals to find the right help in terms of documentation content and resources quickly.
JavaScript
4
star
77

zenoh_evaluation

Zenoh evaluation / Bandwidth test application / Zenoh version
C++
3
star
78

gazebojs

C++
3
star
79

map_transformer

Transform points from one map to another to account for slight differences in maps
C++
3
star
80

ubuntu_armhf-docker

deprecated see https://github.com/osrf/multiarch-docker-image-generation
Shell
3
star
81

mininet_ros

Dockerfile
3
star
82

collision-benchmark

Benchmark tests for collision checking and contact
C++
3
star
83

cloudsim

Shell
3
star
84

oculussdk

C++
2
star
85

open_survey_data

A collection of survey data from the community.
2
star
86

bag_merger

Tool for merging multiple rosbag2 bags into one
C++
2
star
87

romi-js-core-interfaces

Python
2
star
88

vrx-events

Repository containing team submissions for VRX events.
Dockerfile
2
star
89

rosbag_ndk_player

C++
2
star
90

cmbml

C++
2
star
91

iron_irwini_discovery_modes_prototype

Shell
2
star
92

watchprocess

A tool for recording information about executed processes.
Python
2
star
93

buoy_examples

Control examples for wave energy harvesting buoy
C++
2
star
94

handsim

HAPTIX Simulation Utlities
C++
2
star
95

magnum_playground

A place to play with the Magnum rendering engine.
2
star
96

rba_scripts

scripts to help build rosbag for android
Shell
2
star
97

redf

Rust
2
star
98

buildfarm-tools

Ruby
2
star
99

createrepo-agent

Rapidly and repeatedly generate RPM repository metadata
C
2
star
100

ariac-gazebo_ros_pkgs

Fork of https://github.com/ros-simulation/gazebo_ros_pkgs with custom restrictions on which topics can communicate.
C++
2
star