From 4fa9cf4f42dcb80266b868bc369742381f659c27 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mihai=20Capot=C4=83?= <mihai@mihaic.ro>
Date: Mon, 23 Oct 2017 11:13:57 -0700
Subject: [PATCH] dev: Add Dockerfile

Fixes #272.
---
 CONTRIBUTING.rst               |  3 ++-
 Dockerfile                     | 42 ++++++++++++++++++++++++++++++++++
 README.rst                     | 18 +++++++++++++++
 docs/newsfragments/272.feature |  1 +
 4 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 Dockerfile
 create mode 100644 docs/newsfragments/272.feature

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index c1f6d01f4..71c35b6cb 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -212,7 +212,8 @@ Standards
 
 * Create usage examples for new modules in the examples directory. Add a
   ``requirements.txt`` file to help users install the packages your examples
-  require.
+  require. If your example requires software that is not available in PyPI,
+  document it in a ``README.rst`` and also update the BrainIAK Dockerfile.
 
 * Remove the output of example Jupyter notebooks before committing them, using
   `nbstripout <https://pypi.python.org/pypi/nbstripout>`_.
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 000000000..5206c0cdc
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,42 @@
+FROM ubuntu:16.04
+
+# Group 1 must be synced with README
+# Group 2 must be synced with requirements for examples
+# Group 3 must be synced with rest of Dockerfile
+# Group 4 is optional
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    libgomp1 \
+    libmpich-dev \
+    mpich \
+    python3-dev \
+    python3-pip \
+    python3-venv \
+    \
+    curl \
+    unzip \
+    wget \
+    \
+    screen \
+    \
+    less \
+    man \
+    vim
+
+WORKDIR /mnt
+
+RUN set -e \
+    && python3 -m pip install --user -U pip \
+    && python3 -m pip install -U brainiak \
+    && python3 -m pip download --no-deps --no-binary :all: brainiak \
+    && export BRAINIAK_VERSION=$(basename brainiak-* .tar.gz | cut -b 10-) \
+    && tar -xf brainiak-*.tar.gz \
+    && for example in brainiak-$BRAINIAK_VERSION/examples/*/requirements.txt; \
+        do python3 -m pip install --user -U -r $example ; done
+
+RUN echo PATH=\"\$HOME/.local/bin:\$PATH\" >> $HOME/.profile \
+    && echo "shell -bash" >> ~/.screenrc
+
+EXPOSE 8888
+
+ENTRYPOINT ["/bin/bash", "-l"]
diff --git a/README.rst b/README.rst
index ec14783d4..af3a78425 100644
--- a/README.rst
+++ b/README.rst
@@ -106,6 +106,24 @@ Therefore, if you have a problem with an older version, please upgrade to the
 latest version before creating an issue on GitHub.
 
 
+Docker
+======
+
+You can also test BrainIAK without installing it using Docker::
+
+    docker pull brainiak/brainiak
+    docker run -it -p 8888:8888 -v brainiak:/mnt --name demo brainiak/brainiak
+
+To run Jupyter notebooks in the running container, try::
+
+    python3 -m notebook --allow-root --no-browser --ip=0.0.0.0
+
+Then visit http://localhost:8888 in your browser and enter the token. Protip:
+run ``screen`` before running the notebook command.
+
+Note that we do not support MPI execution using Docker containers and that performance will not be optimal.
+
+
 Support
 =======
 
diff --git a/docs/newsfragments/272.feature b/docs/newsfragments/272.feature
new file mode 100644
index 000000000..19669767c
--- /dev/null
+++ b/docs/newsfragments/272.feature
@@ -0,0 +1 @@
+Added a Docker image for testing BrainIAK without installing.