Installing Drake (via Docker)

These are our recommended setup instructions for the Fall 2018 version of MIT 6.881, Robotic Manipulation.

via

Why Drake and Why in Docker?

For class, we want you to have access to all the power of Drake, and using Docker will help us all standardize the development environment for the class.

Here's some background on both of these tools:

• Drake (with Python bindings, pydrake) is a robotics toolbox developed by our lab, with development now lead by the Toyota Research Institute, that we hope can provide a basis for you to solve interesting problems in robotics without having to build many of the detail-intensive components -- for example, robot models, dynamics, simulators, and visualizers. Drake also strives to provide many features (particularly in exposing and preserving computational structure) that can't really be found elsewhere in a comparable tool.


• Docker is a virtual-machine-like container system that makes it easier to maintain a reproducible development environment. A Docker container functions like a separate OS that you can safely make modifications to without modifying your computer's native OS. We will distribute a Docker image that sets up this virtual OS to a configuration that we know will work well with Drake, so that you don't have to do that setup yourself -- and so that if things break, we have a better chance of reproducing your issues.

A big win of the dockerized setup is that we can all run identical Drake on essentially any common distribution of either Windows, Mac, or Linux! (At time of writing, Drake natively supports Ubuntu 18.04 and Mac. We recommend starting with the pre-built Docker image described here, but if you're later interested in contributing back to Drake then you'll want to be building from source.)

Another win is that regardless of the other software on your computer, as long as you can install Docker, then there should be no issues installing Drake.

Overview of Install

There are three overall steps:

1. Make sure your system meets Prerequisites
2. Install Docker
3. Pull down and run a Drake docker container

Prerequisites

• You'll need to be on macOS 10.12 Sierra or higher, or Ubuntu 16.04 or higher. We recommend macOS 10.14 Mojave or Ubuntu 18.04. MIT's Athena cluster machines running these OS's are only experimentally supported, and offer a very poor user experience, so we recommend running your own machine. Other platforms that can run Docker (e.g. Windows, Debian, CentOS, Fedora) might work but we can't promise support. If getting access to a suitable machine is difficult for you, let us know and we can work with you to find a solution.
• You'll need around 10GB free. A single complete Drake image is around 2GB in size (since it contains an entire OS, and a lot of support software), and you may maintain duplicate images, so to be safe, keep around 10GB free.
• You'll want to be on fast internet when you do an install. You'll be sad if you're on slow internet and waiting for a couple gigabytes to download!
• You'll need to use a terminal / command prompt occasionally. If you haven't used one before, you will want to take a few minutes to learn the basics of using one.
• You'll be interacting with Python code via a Jupyter notebook. You can read up on details about what that means here, but you don't really need to know it in-depth. The gist of it is that we'll mostly interact with PyDrake through a web page on which you can edit and run Python code interactively.

Install Docker

First you will need to install Docker, following the instructions below based on your OS.

Pick your platform (click on name of your OS):

Linux | Mac Linux | Mac

$ curl -fsSL get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh

After Docker installation: Pull down and run a Drake docker container

• First let's test Docker. Open your favorite terminal and type:

  $ docker run hello-world

  You should see output indicating that Docker downloaded an image named hello-world and launched it to say ”Hello from Docker!”

• Provided here are utility scripts (download and unzip) for setting up a convenient developer environment:
  • ubuntu and MacOS up to Mojave
  • ubuntu and MacOS Catalina
  The scripts rely on the idea of "mounting" a shared directory -- that is, sharing files between your host OS and the OS within the docker container. Specifically, the scripts take as their second argument a directory that you can edit from both outside the container, as well as inside it at path /psets. This way, work you do inside the container within that directory is saved. You'll usually want to point this path to whatever directory contains your homework code.

  Each zipped folder has two scripts:

  1. For using Jupyter notebooks to interact with the class code.

     docker_run_notebook.sh : This bash script launches the Drake Docker container, using 1) a problem-set-specific tag, which will be provided with each problem set, and 2) a notebook directory, which should be a relative path to where put your problem-set-specific code. E.g.:

     $ ./docker_run_notebook.sh drake-20190901 ./pset0

  2. For using a graphics-enabled bash terminal to run scripts, GUI, full bash control, etc.

     docker_run.py: This python script launches the Drake Docker container, using two non-optional arguments:

     1. --os your operating system, which has to be either mac or linux, and
     2. --drake_tag a problem-set-specific tag, which will be provided with each problem set, and drops you in an interactive bash terminal inside of the container.
     You can use this to, e.g., run python scripts from the command line. For example, if you're on Mac and running pset0, the command would be

     $ python docker_run.py --os mac --drake_tag drake-20190901

     By default, this script mounts the current directory as the /psets directory inside the container. If you would like to mount a different directory, you can add the optional argument -v relative/path/to/desired/dir to the end of the command. For a complete list of the supported optional arguments of this script, run

     $ python docker_run.py --help 

• Run the notebook script from your favorite terminal, using a tag (e.g. drake-20190901) and your current directory:

  $ ./docker_run_notebook.sh drake-20190901 . 

  You'll see a relatively large download happen, and eventually you should see output including:

  ...
  [I 00:33:07.290 NotebookApp] The Jupyter Notebook is running at:
  [I 00:33:07.290 NotebookApp] http://3b768767112e:8080/?token=your_hexadecimal_SHA_number
  [I 00:33:07.290 NotebookApp]  or http://127.0.0.1:8080/?token=your_hexadecimal_SHA_number
  ...

  which means that everything launched OK!

• Open a web browser and point it to

  http://127.0.0.1:8080/?token=your_hexadecimal_SHA_number

This should bring you to the home screen of Jupyter Notebook.

• Start a new Python 3 notebook, and type in the first cell:

  import pydrake
  print("Hello world!")

  Press Control+Enter to run the cell, and you should see "Hello world!" printed below the cell. If this is true, everything works, and you can use PyDrake from this notebook! (Go do a problem set if you want to see something more exciting than text output.)

• Also here is how to run an example with graphics using the python script.

   ## shown for mac below.
  $ python docker_run.py --os mac --drake_tag drake-20190308
  # cd /drake/examples/manipulation_station
  # python end_effector_teleop_sliders.py --meshcat --setup=clutter_clearing

  Open the printed URL (something like http://127.0.0.1:7000/static/) in a browser to open meshcat. You should also see a slider window pop up! (If it doesn't please re-read the Docker install instructions, including XQuartz / X Server items, and make sure you have the latest scripts). If you move the sliders, you should see the robot moving in meshcat.

All done!