This is a template repository to build ROS2 applications capable to run on BinderHub/Docker. The default installed distribution is jazzy Hawksbill, which is a long-term support (LTS) release that will be supported until May 2027. To install a newer or development distribution, change the variable $ROS_DISTRO in Dockerfile.
You can use this repository to do following (and more):
- Learn the ROS2 tutorials without installing anything.
- Quickly start a ROS2 environment in a local Docker container regardless of your operating system.
- Starting to migrate projects from ROS1 to ROS2.
- Create live demos for your ROS2 applications.
-
Try ROS2 jazzy tutorials on BinderHub:
-
Start the "VNC Desktop" in the JupyterLab Launcher to initiate the virtual display before you run GUI applications.
-
Open new launchers tab to start terminals.
-
Arrange tabs by dragging.
-
Most of the installation steps in the tutorials can be skipped.
To connect to real robots or run computate intense robot simulators, you need to run docker containter on your local machine.
A ready-to-run docker image intel4coro/jupyter-ros2:jazzy-py3.11 is pushed to DockerHub.
- Docker Engine
- Ubuntu (Tested with Ubuntu 20.04)
- Nvidia Graphic Card and NVIDIA Container Toolkit (Optional but recommended)
docker run --rm -p 8888:8888 intel4coro/jupyter-ros2:jazzy-py3.11 jupyter lab --NotebookApp.token=''Open url http://localhost:8888/
xhost +local:docker && \
docker run --rm -p 8888:8888 \
-v /tmp/.X11-unix:/tmp/.X11-unix:rw \
--env DISPLAY=$DISPLAY \
--env NVIDIA_DRIVER_CAPABILITIES=all \
--gpus all intel4coro/jupyter-ros2:jazzy-py3.11 && \
xhost -local:dockerRecommended to start with docker-compose if having many custom configurations Example: docker-compose.yml.
You can start a ROS2 project from scratch with this template repository, or create your own ROS2 environment by extending the image intel4coro/jupyter-ros2:jazzy-py3.11, all you need is to create a Dockerfile under the root path or directory binder/ in your git repository. Extending the pre-built image can save a huge amount of time from installing software dependencies.
FROM intel4coro/jupyter-ros2:jazzy-py3.11
# Run bash commands required root permission
USER root
RUN apt update && apt install nano vim
USER ${NB_USER}
# Define environment variables
ENV MY_ROS_WS=/home/${NB_USER}/my-ros-workspace
# Create your ROS workspace
RUN mkdir -p ${MY_ROS_WS}/src
# Change working directory (similar to command "cd")
WORKDIR ${MY_ROS_WS}
# Copy files from your git repo to ROS workspace
COPY --chown=${NB_USER}:users src src/my-repo-name
# Install ROS packages dependencies
RUN rosdep install -i --from-path src --rosdistro ${ROS_DISTRO} -y
# Build ROS workspace
RUN colcon build
# Source ROS workspace in new bash terminals
RUN echo "source ${MY_ROS_WS}/install/setup.bash" >> /home/${NB_USER}/.bashrc
# Override the entrypoint to add startup scripts
# Note: Do not forget to add `exec "$@"` at the end of your entrypoint.
COPY --chown=${NB_USER}:users entrypoint.sh /
ENTRYPOINT ["/entrypoint.sh"]- ros-jazzy-desktop: Desktop install of ROS2 jazzy with RViz, demos, tutorials.
- Jupyterlab: Web-based integrated development environment (IDE)
- VNC Remote Desktop: Run XFCE (or other desktop environments) on Jupyter.
- Webots ROS2 Interface: Package that provides the necessary interfaces to simulate a robot in the Webots Open-source 3D robots simulator.
- Gazebo Classic: Classic Robotic Simulator
Update the Dockerfile to make further changes to the docker image, for example, changing the ROS distribution or removing packages that you don't need. The config of running the docker image on your machine locally is specify in docker-compose.yml.
git submodule update --init-
Run Docker image
docker compose up
-
Open url http://localhost:8888/
-
Force image rebuild after updating the Dockerfile
docker compose up -d --build
To display GUI applications on your host machine instead of a virtual display. Uncomment the following configs in docker-compose.yml
# - /tmp/.X11-unix:/tmp/.X11-unix:rw
# environment:
# - DISPLAY
# - NVIDIA_DRIVER_CAPABILITIES=all
# deploy:
# resources:
# reservations:
# devices:
# - driver: nvidia
# count: all
# capabilities: [gpu]
and run docker compose up with X-forwarding:
xhost +local:docker && \
docker compose up && \
xhost -local:dockerWebots and Gazebo are two advanced robot simulators mentioned in the ROS2 tutorials.
Note: Webots is super graphically demanding simulator, better running it with GPU enabled.
-
Launch Multirobot Example:
ros2 launch webots_ros2_universal_robot multirobot_launch.py -
Type "Y" to install Webots on the first run.
See Webots - ROS2 documenation for more details and github repo cyberbotics/webots_ros2 for more examples.
Note: Gazebo classic doesn't work on our BinderHub instances, will try new Gazebo releases in the future.
Copy Gazebo world demos to directory gazebo_worlds_demo
cp -R /opt/ros/${ROS_DISTRO}/share/gazebo_plugins/worlds /home/${NB_USER}/gazebo_worlds_demo
Explaination of these demos can be found at the beginning of the *.world files.
Open a new terminal under directory gazebo_worlds_demo and launch demos:
gazebo --verbose gazebo_ros_joint_pose_trajectory_demo.world
-
JupyterLab instance crashed when running
colcon buildLimit the number of building threads like this:
colcon build --parallel-workers 2
Copyright 2023 IntEL4CoRo<[email protected]>
This repository is released under the Apache License 2.0, see LICENSE.
Unless attributed otherwise, everything in this repository is under the Apache License 2.0.
This Docker image is based on jupyter/docker-stacks, licensed under the BSD License.
Gazebo example referneces Tiryoh/docker-ros2-desktop-vnc, licensed under the Apache License 2.0.