add initial Dockerfile + docker-compose.yml + docs

still in flux, need guidance on whether `mesa runserver` has formally
replaced `mesa run`

Dockerfile

@@ -0,0 +1,22 @@
+FROM phusion/baseimage:0.11
+# developer Dockerfile for mesa development, installs from local git checkout
+LABEL maintainer="Allen Lee <[email protected]>"
+
+ENV PYTHONUNBUFFERED=1 \
+    LANG=C.UTF-8 \
+    LC_ALL=C.UTF-8
+
+WORKDIR /opt/mesa
+
+COPY . /opt/mesa
+
+RUN apt-get update && apt-get upgrade -y -o Dpkg::Options::="--force-confold" \
+    && apt-get install -y --no-install-recommends \
+    build-essential \
+    python3-dev \
+    python3-pip \
+    python3-setuptools \
+    python3-wheel \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install -e /opt/mesa

README.rst

@@ -61,6 +61,33 @@ For more help on using Mesa, check out the following resources:
 .. _`Email list for users` : https://groups.google.com/d/forum/projectmesa
 .. _`PyPI` : https://pypi.python.org/pypi/Mesa/
 
+Running Mesa in Docker
+------------------------
+
+You can run Mesa in a Docker container in a few ways.
+
+If you are a Mesa developer, first `install docker-compose <https://docs.docker.com/compose/install/>`_ and then run:
+
+.. code-block:: bash
+    
+    $ docker-compose build --pull
+    ...
+    $ docker-compose up -d dev # start the docker container
+    $ docker-compose exec dev bash # enter the docker container that has your current version of Mesa installed at /opt/mesa
+    $ mesa runserver examples/Schelling # or any other example model in examples
+
+ The docker-compose file does two important things: (1) it binds the docker container's port 8521 to your host system's
+ port 8521 so you can interact with the running model as usual by visiting localhost:8521 on your browser, and (2) it
+ mounts the mesa root directory (relative to the docker-compose.yml file) into /opt/mesa and runs pip install -e on that
+ directory so your changes to mesa should be reflected in the running container.
+
+If you are a model developer that wants to run Mesa on a model (assuming you are currently in your top-level model
+directory with the run.py file):
+
+.. code-block:: bash
+
+    $ docker run --rm -it -p127.0.0.1:8521:8521 -v${PWD}:/code comses/mesa:dev mesa runserver /code
+
 Contributing back to Mesa
 ----------------------------
 

docker-compose.yml

@@ -0,0 +1,17 @@
+version: '3'
+services:
+  install:
+    build: .
+    image: mesa:dev
+    command: pip3 install -e /opt/mesa
+    volumes:
+      - .:/opt/mesa
+  dev:
+    image: mesa:dev
+    depends_on:
+      - install
+    volumes:
+      - .:/opt/mesa
+    ports:
+      - "127.0.0.1:8521:8521"
+