Add Dockerfile for Binder (RobotLocomotion#12472)

.binder/.dockerignore

@@ -0,0 +1 @@
+README.md

.binder/Dockerfile

@@ -0,0 +1,34 @@
+# -*- mode: dockerfile -*-
+# vi: set ft=dockerfile :
+
+# TODO(jamiesnape): Use a different tag. Per the Binder documentation, a tag
+# named "latest" is not allowed, however they do not (yet) enforce that
+# restriction.
+FROM robotlocomotion/drake:latest
+ARG NB_USER=jovyan
+ARG NB_UID=1000
+ARG NB_GID=100
+EXPOSE 8888/tcp
+RUN export DEBIAN_FRONTEND=noninteractive \
+  && apt-get update -qq \
+  && apt-get install --no-install-recommends -qq \
+    -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confnew \
+    -o Dpkg::Use-Pty=0 \
+      locales \
+      xvfb \
+  && rm -rf /var/lib/apt/lists/* \
+  && locale-gen en_US.UTF-8 \
+  && useradd -d "/home/$NB_USER" -G $NB_GID -mU -s /bin/bash "$NB_USER"
+USER "$NB_USER"
+ENV HOME="/home/$NB_USER" \
+  LANG=en_US.UTF-8 \
+  LANGUAGE=en_US.UTF-8 \
+  LC_ALL=en_US.UTF-8 \
+  SHELL=/bin/bash \
+  USER="$NB_USER"
+WORKDIR $HOME
+COPY --chown=$NB_UID:$NB_GID \
+  [".binder/binder-entrypoint", "/opt/drake/bin/binder-entrypoint"]
+COPY --chown=$NB_UID:$NB_GID ["tutorials/*.ipynb", "$HOME/tutorials/"]
+ENTRYPOINT ["/opt/drake/bin/binder-entrypoint"]
+CMD ["jupyter", "notebook", "--ip", "0.0.0.0"]

.binder/README.md

@@ -0,0 +1,25 @@
+# Docker Image for Binder
+
+*Note that due to Binder conventions, this directory MUST always be in the root
+of the repository and named either `binder` or `.binder`. This image is NOT
+intended for use by most developers or users. Please use the
+[robotlocomotion/drake](https://hub.docker.com/r/robotlocomotion/drake) image
+from Docker Hub instead.*
+
+To create a Docker image and run a Docker container similar to those used by
+[Binder](https://mybinder.org) for debugging purposes, execute the following
+commands from the top level of the Drake Git repository:
+
+```bash
+docker build -f .binder/Dockerfile -t binder .
+docker run --name mybinder -p 8888:8888 binder
+```
+
+Copy and paste the URL (including the login token) that is displayed in the
+terminal into the web browser of your choice.
+
+To stop the running container, execute the following command in a new terminal:
+
+```bash
+docker stop mybinder
+```

.binder/binder-entrypoint

@@ -0,0 +1,6 @@
+#!/bin/bash -l
+
+set -euxo pipefail
+
+# Some examples need a virtual X server environment for offscreen rendering.
+xvfb-run -a "$@"

doc/index.rst

@@ -48,10 +48,10 @@ Core Library
         </tr>
         <tr>
             <td style="text-align:center">
-                <a target="_doc" href="https://drake.mit.edu/doxygen_cxx/group__systems.html">doc</a> | <a target="_tutorial" href="https://nbviewer.jupyter.org/github/RobotLocomotion/drake/blob/master/tutorials/dynamical_systems.ipynb">tutorial</a>
+                <a target="_doc" href="https://drake.mit.edu/doxygen_cxx/group__systems.html">doc</a> | <a target="_tutorial" href="https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials/dynamical_systems.ipynb">tutorial</a>
             </td>
             <td style="text-align:center">
-                <a target="_doc" href="https://drake.mit.edu/doxygen_cxx/group__solvers.html">doc</a> | <a target="_tutorial" href="https://nbviewer.jupyter.org/github/RobotLocomotion/drake/blob/master/tutorials/mathematical_program.ipynb">tutorial</a>
+                <a target="_doc" href="https://drake.mit.edu/doxygen_cxx/group__solvers.html">doc</a> | <a target="_tutorial" href="https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials/mathematical_program.ipynb">tutorial</a>
             </td>
             <td style="text-align:center">
                 <a target="_doc" href="https://drake.mit.edu/doxygen_cxx/group__multibody.html">doc</a>
@@ -112,7 +112,7 @@ Next steps
 
    gallery
    installation
-   Tutorials <https://nbviewer.jupyter.org/github/RobotLocomotion/drake/tree/master/tutorials/>
+   Tutorials <https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials>
    API Documentation (C++) <doxygen_cxx/index.html#://>
    API Documentation (Python) <pydrake/index.html#://>
    getting_help

tools/install/dockerhub/README.md

@@ -1,3 +1,5 @@
+# Docker Image for Docker Hub
+
 To create a Docker image similar to that hosted on
 [Docker Hub](https://hub.docker.com/r/robotlocomotion/drake), download the
 latest [binary package](https://drake.mit.edu/from_binary.html)

tutorials/README.md

@@ -1,8 +1,8 @@
 # Drake Tutorials
 
-## Running the Tutorials
+## Running the Tutorials Locally
 
-To run the tutorial, you should ensure that you have Drake avaiable, [either via Bazel or via binary packages](https://drake.mit.edu/installation.html).
+To run the tutorials locally, you should ensure that you have Drake available, [either via Bazel or via binary packages](https://drake.mit.edu/installation.html).
 
 To run the notebooks using Bazel, please refer to the
 [Bazel-Jupyter README](../tools/jupyter/README.md#running-notebooks).
@@ -12,23 +12,32 @@ For example:
 bazel run //tutorials:mathematical_program
 ```
 
-## Viewing the Notebooks Online
+## Viewing and Running the Notebooks Online
 
-The notebooks in this folder can be viewed using
-[nbviewer](https://nbviewer.jupyter.org). To see them on Drake `master` on
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials)
+
+The notebooks in this folder can be viewed and run online using
+[Binder](https://mybinder.org). To see them from Drake `master` on
 GitHub, please visit:
-https://nbviewer.jupyter.org/github/RobotLocomotion/drake/tree/master/tutorials/
 
-Presently, these notebooks are not yet set up to be runnable using online
-services. For more information, please see
-[this issue](https://github.com/RobotLocomotion/drake/issues/11962).
+<https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials>
+
+Since Binder uses the `robotlocomotion/drake:latest` image on
+[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake) that is published
+once a day, it may be missing features used by the notebooks on `master`. If you
+encounter issues running a notebook, please try a commit from earlier in the
+day, as close as possible following the publication of the
+`robotlocomotion/drake:latest` image.
 
 ## For Developers
 
 When you add a notebook, please make the first cell be a Markdown cell with the tutorial's title and the following preamble:
 
     For instructions on how to run these tutorial notebooks, please see the
-    [README](./README.md) in this folder.
+    [README](https://github.com/RobotLocomotion/drake/blob/master/tutorials/README.md).
 
-If appropriate, add an `nbviewer` link to the notebook on `master` in the
-documentation.
+If appropriate, add a Binder link to the notebook on `master` in the
+relevant documentation in `/doc`, e.g.,
+```
+https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials/notebook.ipynb`
+```

tutorials/dynamical_systems.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Modeling Dynamical Systems\n",
     "\n",
-    "For instructions on how to run these tutorial notebooks, please see the [README](./README.md) in this folder."
+    "For instructions on how to run these tutorial notebooks, please see the [README](https://github.com/RobotLocomotion/drake/blob/master/tutorials/README.md)."
    ]
   },
   {

tutorials/mathematical_program.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# MathematicalProgram Tutorial\n",
     "\n",
-    "For instructions on how to run these tutorial notebooks, please see the [README](./README.md) in this folder."
+    "For instructions on how to run these tutorial notebooks, please see the [README](https://github.com/RobotLocomotion/drake/blob/master/tutorials/README.md)."
    ]
   },
   {

tutorials/mathematical_program_multibody_plant.ipynb

@@ -7,7 +7,7 @@
     "# Mathematical Program MultibodyPlant Tutorial\n",
     "\n",
     "For instructions on how to run these tutorial notebooks, please see\n",
-    "the [README](./README.md) in this folder."
+    "the [README](https://github.com/RobotLocomotion/drake/blob/master/tutorials/README.md)."
    ]
   },
   {

tutorials/rendering_multibody_plant.ipynb

@@ -7,7 +7,7 @@
     "# Rendering MultibodyPlant Tutorial\n",
     "\n",
     "For instructions on how to run these tutorial notebooks, please see\n",
-    "the [README](./README.md) in this folder."
+    "the [README](https://github.com/RobotLocomotion/drake/blob/master/tutorials/README.md)."
    ]
   },
   {