SC17: reworked module file tutorial section (#5657)

* Reworked module file tutorial section

First draft for the SC17 update. This includes:

 - adding an introduction on module files + Spack's module
   generation blueprints
 - adding a set-up section and provide a docker image for easy set-up
 - updating all the relevant snippets
 - extending a bit some of the concepts that were already touched

* Added reference to #5582 + committed Dockerfiles

Also fixed a couple of typos spotted by Denis.

* module file tutorial: added section on template customization

* module file tutorial: fixed minor typos + rephrased a sentence

* module file tutorial: made explicit that Docker image comes with software

* module file tutorial: improved phrasing and layout.

Thanks Hartzell!

* module file tutorial: added vim and nano to editors

* module file tutorial: fixed typo

* Fixed typos

Thanks Adam!

* module file tutorial: updated Dockerfile + minor changes in introduction

3 files changed, 69 insertions, 0 deletions

diff --git a/share/spack/docs/docker/module-file-tutorial/Dockerfile b/share/spack/docs/docker/module-file-tutorial/Dockerfile
new file mode 100644
index 0000000000..a012492a98
--- /dev/null
+++ b/share/spack/docs/docker/module-file-tutorial/Dockerfile
@@ -0,0 +1,52 @@
+FROM ubuntu:16.04
+
+# General environment for docker
+ENV DEBIAN_FRONTEND=noninteractive \
+    SPACK_ROOT=/usr/local \
+    FORCE_UNSAFE_CONFIGURE=1
+
+# Install system packages
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       autoconf \
+       build-essential \
+       ca-certificates \
+       coreutils \
+       curl man less \
+       emacs-nox vim nano \
+       git \
+       openmpi-bin openmpi-common libopenmpi-dev \
+       python \
+       unzip \
+    &&  rm -rf /var/lib/apt/lists/*      
+
+# Load spack environment on login
+COPY spack.sh /etc/profile
+
+# Install spack
+RUN curl -s -L https://api.github.com/repos/spack/spack/tarball/develop \
+    | tar xzC $SPACK_ROOT --strip 1 
+
+# Copy configuration for external packages
+COPY packages.yaml $SPACK_ROOT/etc/spack/
+
+# Build lmod
+RUN spack install lmod && spack clean -a 
+
+# Build a compiler
+RUN spack install gcc@7.2.0 && spack clean -a
+RUN /bin/bash -l -c ' \
+    spack load gcc@7.2.0 \
+    && spack compiler add'
+
+# Build the software on top of the compiler
+RUN spack install netlib-scalapack ^openmpi ^openblas %gcc@7.2.0 \
+    && spack install netlib-scalapack ^mpich ^openblas %gcc@7.2.0 \
+    && spack install netlib-scalapack ^openmpi ^netlib-lapack %gcc@7.2.0 \
+    && spack install netlib-scalapack ^mpich ^netlib-lapack %gcc@7.2.0 \
+    && spack install py-scipy ^openblas \
+    && spack clean -a
+
+# image run hook: the -l will make sure /etc/profile environments are loaded
+CMD /bin/bash -l
+
diff --git a/share/spack/docs/docker/module-file-tutorial/packages.yaml b/share/spack/docs/docker/module-file-tutorial/packages.yaml
new file mode 100644
index 0000000000..8e3971e61f
--- /dev/null
+++ b/share/spack/docs/docker/module-file-tutorial/packages.yaml
@@ -0,0 +1,9 @@
+packages:
+  git:
+    buildable: False
+    paths:
+      git@2.9.4: /usr
+  openmpi:
+    buildable: False
+    paths:
+      openmpi@1.10.2: /usr
diff --git a/share/spack/docs/docker/module-file-tutorial/spack.sh b/share/spack/docs/docker/module-file-tutorial/spack.sh
new file mode 100644
index 0000000000..54d095c717
--- /dev/null
+++ b/share/spack/docs/docker/module-file-tutorial/spack.sh
@@ -0,0 +1,8 @@
+source $SPACK_ROOT/share/spack/setup-env.sh
+
+LMOD_DIR=$(spack location -i lmod)
+
+if [[ $LMOD_DIR ]] ; then
+    source ${LMOD_DIR}/lmod/lmod/init/bash
+    source $SPACK_ROOT/share/spack/setup-env.sh
+fi