How to docker ubuntu (backport #291) (#379)

Author: mergify[bot]

_scripts/start-docker.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+
+display_usage() {
+    printf "Usage:\n start_docker <name_of_the_container> <name_of_the_image (optional)> <using_gpu (true) (optional)>\n"
+}
+
+if [ -z "$1" ]
+then
+    display_usage
+    exit 1
+else
+  CONTAINER_NAME=$1
+  IMAGE_NAME=$2
+  NO_GPU=$3
+  if (docker ps --all | grep -q "$CONTAINER_NAME")
+  then
+    xhost +local:root &> /dev/null
+    echo "Found a docker container with the given name, starting $1"
+    printf "\n"
+    # If Docker is already running, no need to start it
+    if (docker ps | grep -q "$CONTAINER_NAME")
+    then
+      docker exec -it "$CONTAINER_NAME" /bin/bash && \
+      xhost -local:root 1>/dev/null 2>&1
+    else
+      docker start "$CONTAINER_NAME" 1>/dev/null 2>&1
+      docker exec -it "$CONTAINER_NAME" /bin/bash && \
+      xhost -local:root 1>/dev/null 2>&1
+    fi
+
+  else
+    if [ -z "$2" ]
+    then
+      printf "Can't find docker with the given name, need an image name to start the container from\n"
+      display_usage
+      exit 1
+    else
+      echo "Creating docker container $1 from image $2"
+      printf "\n"
+      if [ -z "$3" ]
+      then
+        xhost +local:root &> /dev/null
+        docker run -it --privileged \
+          --net=host \
+          --gpus all \
+          --env=NVIDIA_VISIBLE_DEVICES=all \
+          --env=NVIDIA_DRIVER_CAPABILITIES=all \
+          --env=DISPLAY \
+          --env=QT_X11_NO_MITSHM=1 \
+          -v /tmp/.X11-unix:/tmp/.X11-unix \
+          --name "$CONTAINER_NAME" \
+          "$IMAGE_NAME" \
+        /bin/bash
+        xhost -local:root 1>/dev/null 2>&1
+      else
+        # Start without GPU
+        echo "Opening up the docker container without GPU support"
+        printf "\n"
+        xhost +local:root &> /dev/null
+        docker run -it --privileged \
+            --net=host \
+            --env=DISPLAY \
+            --env=QT_X11_NO_MITSHM=1 \
+            -v "/tmp/.X11-unix:/tmp/.X11-unix" \
+            --name "$CONTAINER_NAME" \
+            "$IMAGE_NAME" \
+            /bin/bash
+        xhost -local:root 1>/dev/null 2>&1
+      fi
+    fi
+  fi
+fi

doc/how_to_guides/how_to_guides.rst

@@ -8,3 +8,4 @@ These how-to guides will help you quickly solve specific problems using MoveIt.
 
    how_to_guide
    how_to_generate_api_doxygen_locally
+   how_to_setup_docker_containers_in_ubuntu

doc/how_to_guides/how_to_setup_docker_containers_in_ubuntu.rst

@@ -0,0 +1,77 @@
+How to Set Up MoveIt 2 Docker Containers in Ubuntu
+===================================================
+This guide will provide a walkthrough on how to get a Docker container with MoveIt 2 dependencies set up quickly.
+It includes a script that will get you up and running in MoveIt quickly!
+This guide is intended for people who would like to have a separate environment for working with MoveIt up and running quickly \
+without having to do much configuring. In this guide, we will be setting up a ROS2 Humble environment.
+
+Learning Objectives
+-------------------
+
+- How to setup a Docker environment using the provided script
+
+Requirements
+------------
+
+- Ubuntu 20.04 or 22.04
+- `Docker Installation for Ubuntu <https://docs.docker.com/engine/install/ubuntu/>`_
+- `Nvidia drivers for Docker <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#setting-up-nvidia-container-toolkit>`_
+
+Steps
+-----
+1. Install Docker (a link is available in the Requirements section) and be sure to follow the `Linux Post Install <https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user>`_ instructions. If you do not complete these additional steps you will need to preface all ``docker`` commands with ``sudo``.
+
+2. Open a terminal session, download the Docker script, and make it executable.
+
+  .. code-block:: bash
+
+    wget https://raw.githubusercontent.com/abake48/moveit2_tutorials/how-to-docker-ubuntu/_scripts/start-docker.sh -O ~/.local/bin/start-docker.sh
+    chmod +x ~/.local/bin/start-docker.sh
+
+3. Run the script.
+
+  There are 3 parameters for the script:
+      - ``name_of_the_container`` : this is the name you wish to give the created container. For this guide, we will be naming the container ``moveit2-humble``.
+      - ``name_of_the_image`` : if you are creating a fresh Docker container, provide the name of the Docker image here. For this guide, we will be using the image ``moveit/moveit2:humble-source``. Further explanation of this parameter is provided in the ``Further Reading`` section.
+      - ``using_gpu`` : if ``true``, the Docker will be run using Nvidia GPU drivers. By default, this value is true.
+
+  To run the script and use Nvidia GPU drivers
+
+  .. code-block:: bash
+
+    start-docker.sh moveit2-humble moveit/moveit2:humble-source
+
+  If the above command fails, it is likely that Nvidia drivers cannot be used or are installed correctly. In which case, you can still proceed without using Nvidia drivers!
+  First, you'll need to remove the container you just created by running the following command:
+
+  .. code-block:: bash
+
+    docker rm moveit2-humble
+
+  Then, to run the Docker container without the Nvidia drivers, run the following command:
+
+  .. code-block:: bash
+
+    start-docker.sh moveit2-humble moveit/moveit2:humble-source false
+
+  Running the script for the first time creates, starts, and executes the container ``moveit2-humble``.
+
+4. You should now be inside of your Docker container, in the workspace directory. You should now be able to start working with MoveIt!
+
+  Whenever you wish to reenter your container, you can run the following command:
+
+  .. code-block:: bash
+
+    start-docker.sh moveit2-humble
+
+Further Reading
+---------------
+- For more information about Docker best practices with respect to MoveIt,
+  refer to `this blog post <https://picknik.ai/ros/robotics/docker/2021/07/20/Vatan-Aksoy-Tezer-Docker.html>`_
+  from PickNik's Vatan Aksoy Tezer and Brennard Pierce.
+
+- You can find a list of tagged images for the MoveIt 2 Docker container `here <https://hub.docker.com/r/moveit/moveit2/tags>`_.
+  The tagged images coincide with ROS2 version releases. The ``release`` version of the container provides an environment in which MoveIt 2 is installed via the binaries.
+  The ``source`` version of the Docker image will build MoveIt 2 from source.
+  You can use any of the images in that link by substituting the second parameter in the script, ``name_of_the_image``, with moveit/moveit2:<tag_name>, where ``<tag_name>`` is from the above link.
+  For example, this guide instructs you to use the image with the tag ``humble-source``.