From 6f2398a4131163c0e05c30547daa350d0e8be56d Mon Sep 17 00:00:00 2001 From: "Brandon D. Northcutt" Date: Fri, 26 May 2017 08:39:46 -0700 Subject: [PATCH] Added Docker images to run Ubuntu 16.04 Bazel built Drake with visualization support. --- drake/doc/docker.rst | 262 ++++++++++++++++++ drake/doc/index.rst | 25 +- drake/doc/installation.rst | 1 + setup/docker/Dockerfile.ubuntu16.04.nvidia | 9 + .../docker/Dockerfile.ubuntu16.04.opensource | 9 + setup/docker/entrypoint.sh | 15 + setup/ubuntu/16.04/install_prereqs.sh | 2 +- 7 files changed, 312 insertions(+), 11 deletions(-) create mode 100644 drake/doc/docker.rst create mode 100644 setup/docker/Dockerfile.ubuntu16.04.nvidia create mode 100644 setup/docker/Dockerfile.ubuntu16.04.opensource create mode 100755 setup/docker/entrypoint.sh diff --git a/drake/doc/docker.rst b/drake/doc/docker.rst new file mode 100644 index 000000000000..41b8a9eff20c --- /dev/null +++ b/drake/doc/docker.rst @@ -0,0 +1,262 @@ +.. _docker_entry: + +Building Drake in a Docker Container +************************************ + +.. _docker_intro: + +Introduction +============ +Docker containers have emerged as a solution to running code or services in a +way that is isolated from the host operating system. This allows code to be +compiled and run on systems running unsupported operating systems or with +incompatable configurations to the software dependencies. Docker is available +for `all major operating systems `_. + +Two Docker containers are provided with Drake to allow developers to test and +develop without needing to configure a supported operating system. These +containers will build Drake in isolated Ubuntu 16.04 environments. + +The Nvidia Dockerfile is based upon the nvidia docker plugin base image, which +also contains CUDA support. The opensource Dockerfile is based on the +the vanilla Ubuntu 16.04 image and is intended to support opensource graphics +card drivers such as nouveau and intel. Should you need to build inside of +another base image (FROM line in the Dockerfile), they are available `here +`_. + +Note: This docker image is provided as an experimental feature and is not +presently covered by continuous integration. + +.. _docker_getting_started: + +Getting Started +=============== +In order to get docker installed, please follow guides specific to your +operating system. The typical steps are: + + #. Install docker from your distribution's package manager or official installer + from `Docker + `_ + + #. Enable Docker to run as a daemon/service + #. Add appropriate users to the docker group to give permissions to interact + with the Docker service + + #. Log out and back in to update user groups + #. Happy dockering! + +These steps on Ubuntu 16.04 x86_64 are: + +:: + + $ wget https://download.docker.com/linux/ubuntu/dists/xenial/pool/stable/amd64/docker-ce_17.03.1~ce-0~ubuntu-xenial_amd64.deb + $ sudo dpkg -i docker-ce_17.03.1~ce-0~ubuntu-xenial_amd64.deb + $ sudo systemctl start docker + $ sudo usermod -aG docker + +Log out and then back in. + +.. _docker_building: + +Building +======== + +Clone the Drake source code as described in :ref:`Getting Drake`. + +The the following build commands will copy the full directory +from your host machine into the Docker container where it may be built and run. + +Nvidia +~~~~~~ +When using the Nvidia proprietary drivers: + +:: + + $ cd + $ docker build -t drake -f setup/docker/Dockerfile.ubuntu16.04.nvidia . + +Open Source +~~~~~~~~~~~ +When using open source video drivers (nouveau, intel, ...): + +:: + + $ cd + $ docker build -t drake -f setup/docker/Dockerfile.ubuntu16.04.opensource . + +If successful + +:: + + $ docker images + +should show an image named drake and + +:: + + $ docker ps + +will show any running Docker containers on your system. + +.. _docker_running: + +Running +======= + +.. _docker_running_simulation: + +The simplest run command is + +:: + + $ docker run -it drake bash + +which will give you bash shell access to the Ubuntu 16.04 Docker container +where you can run commands such as: + +:: + + $ cd /drake-distro + $ bazel build //... + $ bazel test //... + +These commands will build all packages using bazel and run all tests. + +Graphical Interface +~~~~~~~~~~~~~~~~~~~ + +The run command in order to get graphical interfaces from the Docker container +is a bit more involved. Two systems are described below one with Nvidia +proprietary graphics card drivers and one with open source drivers like Nouveau +and Intel. + +.. _docker_running_simulation_nvidia: + +Nvidia drivers: +--------------- +The `nvidia-docker `_ plugin is +required in order to pass Xorg drawing commands to your host system when the +proprietary Nvidia GPU drivers are installed. To install Nvidia GPU drivers with +apt on Ubuntu 16.04:: + + $ sudo apt-get nvidia-361 nvidia-modprobe + +To install nvidia-docker on Ubuntu 16.04: + +:: + + $ wget -P /tmp https://github.com/NVIDIA/nvidia-docker/releases/download/v1.0.1/nvidia-docker_1.0.1-1_amd64.deb + $ sudo dpkg -i /tmp/nvidia-docker*.deb && rm /tmp/nvidia-docker*.deb + $ nvidia-docker run --rm nvidia/cuda nvidia-smi + + +:: + + $ xhost +local:root; nvidia-docker run -i --rm -e DISPLAY \ + -e QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix \ + --privileged -t drake; xhost -local:root + +The default command defined behavior will start the Drake visualizer and run +the bowling ball simulation. + +Walking through this command:: + + $ xhost +local + +will allow access for non-network connections to your local X server and pass +the necessary X11 parameters for graphical display of programs within the Docker +container.:: + + docker-nvidia + +is an Nvidia plugin that couples with the proprietary Nvidia drivers and gives +access to advanced features like CUDA. + +The:: + + -i + +switch assigns a tty for interactive text connections within +the console.:: + + --rm + +will clean up after the image, omit this to allow the container's file system to +persist.:: + + -e DISPLAY + +Forwards your host DISPLAY environment variable to the Docker container.:: + + -e QT_X11_NO_MITSHM=1 + +specifies to not use the MIT magic cookie.:: + + -v /tmp/.X11-unix:/tmp/.X11-unix + +shares the host .X11 interface with the Docker container as a volume.:: + + --privileged + +is only needed on selinux systems.:: + + -t drake + +provides the Docker container name and:: + + $ xhost -local:root + +removes the permission given earlier for local non-network connections to X. + + +See the `Docker Run Reference +`_. For more information on +run options. + +It is also possible to enter a bash shell for interactive development with: + +:: + + $ xhost +local:root; nvidia-docker run -i --rm -e DISPLAY \ + -e QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix \ + --privileged -t drake bash; xhost -local:root + +where you may want to try various demonstrations, e.g.: + +:: + + $ cd /drake-distro + $ bazel run //drake/examples/contact_model:bowling_ball + $ bazel run //drake/examples/kuka_iiwa_arm:kuka_simulation + $ bazel run //drake/examples/kuka_iiwa_arm/dev/monolithic_pick_and_place:monolithic_pick_and_place_demo + + +Note: these are currently not rendering properly due to VTK .obj/.mtl importing. + + +.. _docker_running_simulation_open: + +Open source drivers: +~~~~~~~~~~~~~~~~~~~~ +With open source graphics drivers like Nouveau and Intel you do not need the +nvidia-docker plugin. + +:: + + $ xhost +local:root; docker run -i --rm -e DISPLAY \ + -e QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix \ + --privileged -t drake; xhost -local:root + + +Sharing Files Between Host and Docker: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to interactively develop and compile within the Docker container. +Several options exist for retaining code altered or generated within the +Docker image. `Docker cp +`_ can be used +to copy files into and out of a running image. +`-v `_ +can be used to mount a host directory inside the Docker image at the expense +of file system isolation. Or you can use git commands interactively inside the +container to push code changes directly to a repository. diff --git a/drake/doc/index.rst b/drake/doc/index.rst index e50ac26a3fd7..c0f9693afffe 100644 --- a/drake/doc/index.rst +++ b/drake/doc/index.rst @@ -131,16 +131,21 @@ The Drake developers would like to acknowledge significant support from the `Toy Next steps ========== .. toctree:: - :maxdepth: 1 - - installation - developers - Doxygen (C++) - faq - issues - Mailing list - credits - GitHub + :maxdepth: 1 + + gallery + installation + Introduction and Examples + design + developers + Doxygen (C++) + models + faq + issues + video_tutorials + Mailing list + credits + GitHub Using Drake from other Programming Languages diff --git a/drake/doc/installation.rst b/drake/doc/installation.rst index 875e58c9c783..4dd59b424f10 100644 --- a/drake/doc/installation.rst +++ b/drake/doc/installation.rst @@ -16,6 +16,7 @@ You can choose to download a pre-compiled version of Drake, or to build it from from_binary from_source + docker Optional: Installing MATLAB diff --git a/setup/docker/Dockerfile.ubuntu16.04.nvidia b/setup/docker/Dockerfile.ubuntu16.04.nvidia new file mode 100644 index 000000000000..1cfcea5c4d63 --- /dev/null +++ b/setup/docker/Dockerfile.ubuntu16.04.nvidia @@ -0,0 +1,9 @@ +FROM nvidia/cuda:8.0-devel-ubuntu16.04 +RUN mkdir /drake-distro +COPY . /drake-distro +RUN apt-get update && yes "Y" \ + | /drake-distro/setup/ubuntu/16.04/install_prereqs.sh \ + && rm -rf /var/lib/apt/lists/* \ + && apt-get clean all +RUN cd /drake-distro && bazel build //tools:drake_visualizer && bazel build //drake/examples/Acrobot:acrobot_run_passive +ENTRYPOINT ["/drake-distro/setup/docker/entrypoint.sh"] diff --git a/setup/docker/Dockerfile.ubuntu16.04.opensource b/setup/docker/Dockerfile.ubuntu16.04.opensource new file mode 100644 index 000000000000..13764a6180f0 --- /dev/null +++ b/setup/docker/Dockerfile.ubuntu16.04.opensource @@ -0,0 +1,9 @@ +FROM ubuntu:16.04 +RUN mkdir /drake-distro +COPY . /drake-distro +RUN apt-get update && yes "Y" \ + | /drake-distro/setup/ubuntu/16.04/install_prereqs.sh \ + && rm -rf /var/lib/apt/lists/* \ + && apt-get clean all +RUN cd /drake-distro && bazel build //tools:drake_visualizer && bazel build //drake/examples/Acrobot:acrobot_run_passive +ENTRYPOINT ["/drake-distro/setup/docker/entrypoint.sh"] diff --git a/setup/docker/entrypoint.sh b/setup/docker/entrypoint.sh new file mode 100755 index 000000000000..6bf0ebbdfaf3 --- /dev/null +++ b/setup/docker/entrypoint.sh @@ -0,0 +1,15 @@ +#!/bin/bash +#This file is a script that defines the default run behavior of the Docker +#image. If no command line arguments are given, it will run the passive Acrobot +#demo, else it will execute privided arguments in a Bash shell. +set -e -u +[[ $# -eq 0 ]] && { +# TODO (brandon-northcutt) run the visualizer produced from Bazel + cd /drake-distro + bazel build //tools:drake_visualizer + ./bazel-bin/tools/drake_visualizer& + sleep 2 + bazel run //drake/examples/Acrobot:acrobot_run_passive +} || { + eval "$@" +} diff --git a/setup/ubuntu/16.04/install_prereqs.sh b/setup/ubuntu/16.04/install_prereqs.sh index 66b485216cc0..c0ee76a92cf9 100755 --- a/setup/ubuntu/16.04/install_prereqs.sh +++ b/setup/ubuntu/16.04/install_prereqs.sh @@ -26,7 +26,7 @@ while true; do read -p "Do you want to continue? [Y/n] " yn case $yn in [Yy]*) - apt-get install --no-install-recommends lsb-core software-properties-common wget + apt-get install --no-install-recommends lsb-core software-properties-common wget sudo wget -q -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - add-apt-repository -y "deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-3.9 main" apt-get update