diff --git a/_scripts/start-docker.sh b/_scripts/start-docker.sh new file mode 100644 index 0000000000..514d02d3a3 --- /dev/null +++ b/_scripts/start-docker.sh @@ -0,0 +1,72 @@ +#!/bin/bash + +display_usage() { + printf "Usage:\n start_docker \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 diff --git a/doc/how_to_guides/how_to_setup_docker_containers_in_ubuntu.rst b/doc/how_to_guides/how_to_setup_docker_containers_in_ubuntu.rst new file mode 100644 index 0000000000..dd04c822f4 --- /dev/null +++ b/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 Foxy environment. + +Learning Objectives +------------------- + +- How to setup a Docker environment using the provided script + +Requirements +------------ + +- Ubuntu 20.04 or 22.04 +- `Docker Installation for Ubuntu `_ +- `Nvidia drivers for Docker `_ + +Steps +----- +1. Install Docker (a link is available in the Requirements section) and be sure to follow the `Linux Post Install `_ 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-foxy``. + - ``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:foxy-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-foxy moveit/moveit2:foxy-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-foxy + + Then, to run the Docker container without the Nvidia drivers, run the following command: + + .. code-block:: bash + + start-docker.sh moveit2-foxy moveit/moveit2:foxy-source false + + Running the script for the first time creates, starts, and executes the container ``moveit2-foxy``. + +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-foxy + +Further Reading +--------------- +- For more information about Docker best practices with respect to MoveIt, + refer to `this blog post `_ + from PickNik's Vatan Aksoy Tezer and Brennard Pierce. + +- You can find a list of tagged images for the MoveIt 2 Docker container `here `_. + 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:, where ```` is from the above link. + For example, this guide instructs you to use the image with the tag ``foxy-source``. diff --git a/index.rst b/index.rst index 2f81e0d011..1e1f8039c0 100644 --- a/index.rst +++ b/index.rst @@ -59,6 +59,7 @@ Miscellaneous :maxdepth: 1 doc/realtime_servo/realtime_servo_tutorial + doc/how_to_guides/how_to_setup_docker_containers_in_ubuntu API Documentation -----------------