Host Jupyter lab notebooks with ready access to PyDrake and Meshcat

1. Clone this repo and cd to it
2. You’ve got two options to run the container:

   a. Build the image and spin it up

   docker build \
       --build-arg UID=$(id -u) \
       --build-arg GID=$(id -g) \
       --build-arg UNAME=$USER \
       . -t jdm:latest
   
   docker run -it \
       -p 8888:8888 -p 7000-7100:7000-7100 \
       -v $PWD/sample:/jupyter/sample \
       --user $(id -u):$(id -g) \
       jdm:latest
       

   b. Just use docker-compose: UID=${UID} GID=${GID} docker-compose up

3. Follow the prompts to open Jupyter Lab in your browser. From there, check out sample/intro.ipynb, which demonstrates sample interactions with Drake and Meshcat.
4. The docker-compose file and sample docker run command above both mount the sample/ directory into the container. Feel free to change it to any other directory on your machine. We also ensure that Jupyter doesn’t change file permissions, so you should have no problem with the permissions of any notebooks you create or modify in Jupyter.

This repo uses literate programming - the source code for the Dockerfile and docker-compose.yml file are written below and tangled to their final destinations.

The drake image seems to be more system agnostic than the manipulation image from the MIT 6.843 problem sets, which are meant to run on deepnote.com. There are some helpful visualization python libraries in manipulation, so we’ll copy them over (we should probably just download this directory directly instead of copying from manipulation.)

FROM russtedrake/manipulation:latest as manipulation
FROM robotlocomotion/drake:focal as drake

Install system dependencies. Use tini as an init system.

RUN apt-get update && apt-get upgrade -y && apt install -y \
    build-essential \
    nginx \
    python3-dev \
    python3-venv \
    xvfb

ADD https://github.com/krallin/tini/releases/download/v0.19.0/tini /usr/bin/tini
RUN chmod +x /usr/bin/tini

Create a user that matches the host UID and GID (simplifies file management for volume mounted directories).

ARG UNAME=user
ARG UID=1000
ARG GID=1000
RUN groupadd -g $GID -o $UNAME
RUN useradd -m -u $UID -g $GID -o $UNAME && \
  mkdir -p /jupyter && \
  chown -R $UNAME:$UNAME /jupyter
USER $UNAME

Setup the working directory and install python dependencies

WORKDIR /jupyter
RUN python -m venv .venv
COPY requirements.txt .
RUN .venv/bin/pip install -r requirements.txt

Copy python libraries from manipulation to the venv.

COPY --from=manipulation /opt/manipulation/manipulation/ .venv/lib/python3.8/site-packages/manipulation

Expose ports and run Jupyter lab when the container spins up.

# default port for jupyter
EXPOSE 8888
# meshcat will use port 7000 first, then increment by 1 for each subsequent instantiation
EXPOSE 7000-7100

ENTRYPOINT ["/usr/bin/tini", "--"]
CMD [".venv/bin/jupyter", "lab", "--no-browser", "--ip=0.0.0.0"]

version: "3"
services:
  app:
    build: .
    ports:
      - 8888:8888
      - 7000-7100:7000-7100
    volumes:
      - ./sample:/jupyter/sample

Use your own UID and GID in Jupyter to simplify notebook file permissions. If you don’t do this, all files created in notebooks will be owned by root.

user: "${UID}:${GID}"
group_add:
  - users