Installing Drake (via Docker)
These are our recommended setup instructions for the Spring 2019 version of MIT 6.832, Underactuated Robotics.
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 16.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:
- Make sure your system meets Prerequisites
- Install Docker
- Pull down and run a Drake docker container
- You'll need to be on 64-bit Ubuntu 14.04 or higher, Mac 10.10.3 Yosemite or higher, or Windows 10 or 7. 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. 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.
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 | Windows Linux | Mac | Windows Linux | Mac | Windows
Follow the instructions here for your system. We will only officially support Ubuntu 16.04 but you can probably get other systems working too.
The easiest of install methods, if you trust Docker, is to just run these scripts:
curl -fsSL get.docker.com -o get-docker.sh sudo sh get-docker.sh
Now you can go to the After Docker Installation section!
Docker has a friendly double-click-happy install on Mac:
- Go to the Docker-for-mac install page.
- Click on "Download from Docker Hub" and download the .dmg file (about 550 MB).
- Double-click the .dmg, and follow the install instructions. Refer to this page if you have any questions.
We recommended you to install XQuartz too. Without XQuartz, you will only be able to run examples with visualizations through iPython notebooks. Install and setup steps are:
- Install XQuartz 2.7.11 from the official website (click on 2.7.11) from the official website, or
brew cask installit if you prefer.
- Open up XQuartz (if you installed from website, then just run Spotlight (cmd+space), search for XQuartz and press enter)
- Go to XQuartx-->Preferences-->Security and "Allow connections from network devices"
- Quit XQuartz, this will lock in the changed preferences.
- Per the instructions here, make sure that you logout and log back in to OSX in order to update your DISPLAY environment.
- In future, before you run
./docker_run_bash_mac.sh, you'll need to reopen XQuartz and leave it open.
Now you can go to the After Docker Installation section!
Windows 10 (Except Home)
- Download Docker:
- If you do not already use VirtualBox, download Docker (use the "Stable" channel) from here and install it.
- If you have trouble with the above, or if you already use VirtualBox and want it to keep working, instead follow the instructions for Windows 7. (See the info here for details about what Docker requires and expects on Windows, and how it might interact with VirtualBox or other VM systems on Windows.)
- Search for Docker in your start menu and start "Docker for Windows."
- You should see a Docker app running in your tray once that launches successfully. Now you can go to the After Docker Installation section!
Windows 7 + Windows 10 Home
- Download Docker Toolbox for Windows from here and install it.
- Run the newly installed "Docker Quickstart" program. It will open a terminal and take a few moments, but will present you with a terminal from which you can run Docker. (Unlike other OSs, you can only run Docker from this particular terminal when using Docker Toolbox / Windows 7.)
- Now you can go to the After Docker Installation section, using the Docker Quickstart terminal to enter commands!
Setting up an X ServerThese instructions apply for either Windows 10 or 7, and are required if you want graphical windows to appear when using the command line (when invoking Python scripts, for example) within the Docker container. If you only view results through the Jupyter notebooks, you can skip this step.
- Install Xming from here (or otherwise procure an X server for your host OS).
- Make sure Xming is not running (check the process tray) and run XLaunch from the start menu. Click through, accepting the default options, until you get the option to enable no access control. Enable that and continue with defaults for everything else. XMing should launch and appear in your process tray.
After Docker installation: Pull down and run a Drake docker container
First let's test Docker. Open your favorite terminal (unless you’re on Windows 7 – y’all have to use the Docker Quickstart terminal) and type:
docker run hello-world
You should see output indicating that Docker downloaded an image named
hello-worldand launched it to say ”Hello from Docker!”
Provided here are utility scripts (download and unzip) for setting up a convenient developer environment. Both of these 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, both scripts take as their second argument a directory that you can edit from both outside the container, as well as inside it at path
/notebooks. 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.
There are two types of scripts:
For using Jupyter notebooks to interact with the class code.
docker_run_notebook scripts : These launch 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.:
A batch version is provided for Windows 10 users. Everyone else (including Docker Toolbox users on Windows 7) should use the .sh files.
./docker_run_notebook.sh drake-20190129 ./set_1_code
For using a bash terminal to run scripts, full bash control, etc.
docker_run_bash scripts: These launch the Drake Docker container, using 1) 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, and 2) a notebook directory to mount inside the container at
/notebooks. You can use this to, e.g., run python scripts from the command line. A MinGW-specific version is provided for Docker Toolbox users, and a batch file is provided for Windows 10 users. These both require a 3rd argument: your computer's IP, as you can find from ipconfig.
These scripts vary more for different platforms:
# use the script that matches your platform ./docker_run_bash_linux.sh drake-20190129 . ./docker_run_bash_mac.sh drake-20190129 . ./docker_run_bash_mingw.sh drake-20190129 . ./docker_run_bash_win10.sh drake-20190129 .
Run the notebook script from your favorite terminal, using a tag (e.g. drake-20190129) and your current directory:
# on most platforms ./docker_run_notebook.sh drake-20190129 .
# on Windows 10 ./docker_run_notebook.bat drake-20190129 .
You'll see a relatively large download happen, and eventually you should see output including:
... [I 23:55:17.862 NotebookApp] The Jupyter Notebook is running at: [I 23:55:17.862 NotebookApp] http://(efbfe75d7289 or 127.0.0.1):8080/ ...
which means that everything launched OK!
Open a web browser and point it to the appropriate hostname based on your OS:
- Linux and Mac: http://127.0.0.1:8080/
- Windows 10: http://127.0.0.1:8080/
- Windows 7: Open a new Docker Quickstart terminal and run
docker-machine ipto get an IP address. Use http://[that IP]:8080/
Start a new Python 2 notebook, and type in the first cell:
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.)
import pydrake print "Hello world!"
Also here is how to run the examples from the textbook, using the bash scripts.
## shown for linux below, or use the docker_run_bash script for your system ./docker_run_bash_linux.sh drake-20190129 . ## the textbook is already inside the docker image, at /underactuated cd /underactuated/src/double_pendulum python simulator.py
You should see a double pendulum simulation 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.)
Check out this example of what's to come soon in the class.