Clean up build, add docs

Dockerfile

@@ -1,18 +1,38 @@
+# Base ourselves on the Stackage Nightly image to get all necessary system
+# libraries. This also pulls in an unnecessary GHC, but we're favoring
+# simplicity here.
 FROM snoyberg/stackage:nightly
 
-RUN curl http://downloads.haskell.org/~ghc/8.0.1-rc2/ghc-8.0.0.20160204-x86_64-deb8-linux.tar.xz > ghc.tar.xz && \
+RUN echo Starting && \
+
+    # Download the GHC tarball, feel free to update the URL as necessary
+    curl http://downloads.haskell.org/~ghc/8.0.1-rc2/ghc-8.0.0.20160204-x86_64-deb8-linux.tar.xz > ghc.tar.xz && \
+
+    # Decompress the tarball and delete it (make the resulting image smaller)
     tar xf ghc.tar.xz && \
     rm ghc.tar.xz && \
+
+    # Install GHC to /opt/ghc
     cd ghc-* && \
     ./configure --prefix=/opt/ghc && \
     make install && \
     cd .. && \
+
+    # Remove the unpacked directory
     rm -rf ghc-* && \
+
+    # Hopefully this is just an artifact of RCs and not a sign of changing the
+    # directory structure permanently...
     mv /opt/ghc/share/doc/ghc-* /opt/ghc/share/doc/ghc && \
+
+    # Get the stack and stackage-curator executables
     curl -L https://www.stackage.org/stack/linux-x86_64 | tar xz --wildcards --strip-components=1 -C /usr/bin '*/stack' && \
     curl https://s3.amazonaws.com/stackage-travis/stackage-curator/stackage-curator.bz2 | bunzip2 > /usr/bin/stackage-curator && \
     chmod +x /usr/bin/stackage-curator
 
+# Update environment to use the new GHC
 ENV PATH=/opt/ghc/bin:$PATH
 
+# Include the README.md file and build.sh script
+ADD README.md /stackage/README.md
 ADD build.sh /stackage/build.sh

README.md

@@ -1,2 +1,22 @@
 # ghc-rc-stackage
+
 Helper repo for testing GHC release candidates against the Stackage package set
+
+This repo contains a Dockerfile for generating a Docker image with the relevant
+GHC, system libraries, and a `/stackage/build.sh` script for running the build.
+See each of those files for more information. You can build the Docker image
+yourself if desired with:
+
+    docker build --tag fpco/ghc-rc-stackage .
+
+This can be especially useful if you want to point to a newer GHC tarball than
+referenced in this repo (though please consider sending a PR when new release
+candidates are available). You can pull the latest upstream image with:
+
+    docker pull fpco/ghc-rc-stackage
+
+Regardless of whether you have a self-built or upstream Docker image, the
+recommended approach for running it is to bind mount the build directory to
+your host so you can analyze build objects and logs. A script for that is:
+
+    docker run --rm -it -v `pwd`/build:/build -v `pwd`/fake-home:/fake-home -e USERID=`id -u` fpco/ghc-rc-stackage /stackage/build.sh

build.sh

@@ -2,13 +2,46 @@
 
 set -eux
 
+# Create stackage user inside container
+useradd -u $USERID -d /fake-home stackage
+export HOME=/fake-home
+
+# Fix permissions on work directories
+mkdir -p /fake-home /build
+chown stackage /fake-home /build
+
+# Change to the correct directory
+cd /build
+
+# Find out the latest nightly snapshot available
 NIGHTLY=$(curl -i https://www.stackage.org/nightly | grep '^Location:' | sed 's@^Location: /@@' | sed 's@\r@@')
+
+# Download the yaml file for that snapshot
 curl https://raw.githubusercontent.com/fpco/stackage-nightly/master/$NIGHTLY.yaml > plan.yaml
+chown stackage plan.yaml
+
+# Prime the package index
+sudo -u stackage stack update
+mkdir tmp
+chown stackage tmp
+(cd tmp && sudo -u stackage stack unpack random)
+rm -rf tmp
+
+# Kick off the build. Some details on options:
 
-exec stackage-curator make-bundle \
+# * plan-file is the input file downloaded above
+# * docmap and bundle files are unused output files (for uploading only)
+# * similarly, the target only affects upload
+# * allow-newer and no-rebuild-cabal are special arguments for RC builds:
+# ignore version bounds, and don't rebuild the Cabal library (we need the one
+# bundled with GHC)
+sudo -u stackage env "PATH=$PATH" "HOME=$HOME" stackage-curator make-bundle \
     --plan-file plan.yaml \
+    \
     --docmap-file docmap.yaml \
-    --bundle-file bundle.yaml \
+    --bundle-file bundle.bundle \
+    \
     --target nightly-$(date "+%Y-%m-%d") \
+    \
     --allow-newer \
     --no-rebuild-cabal