Update README.rst

Tried adding some new documentation on extending the Docker image (this is pretty general documentation
for adding packages in Docker images, but the note about the user is not immediately obvious)
CC @JohnCremona

Author: embray

README.rst

@@ -72,16 +72,57 @@ It also targets a much broader community, with the potential to
 relieve the SageMath community from maintaining a custom solution.
 On the other hand it's still relatively recent and quickly evolving
 technology with less settled sustainability. Also the SageMath Cell
-has been optimized to be more reactive on startup and reduce
+has been optimized to be more reactive on startup and reduceapt
 resource consumption. Those optimizations have not yet been ported to
 Thebe+binder.
 
 See also `thebe.rst <thebe.rst>`_ for additional reader-oriented notes.
 
+Extending the sagemath Docker image
+-----------------------------------
+
+The sample [`Dockerfile`](https://github.com/sagemath/sage-binder-env/blob/master/Dockerfile)
+in this repository is based on the official `sagemath/sagemath` Docker image.  It includes
+Sage itself, and all the software packages typically included in a standard Sage installation,
+though not *everything* (in particular not optional Sage SPKGs, or other system software
+packages).
+
+So in order to install additional Sage SPKGs it is possible to include a line like
+
+    RUN sage -i <spkg-name>
+    
+in the `Dockerfile`.  Note, due to a current shortcoming in the official Docker image it is
+also necessary to install the `make` system package before running `sage -i`.  See the
+next section.
+
+Installing additional system packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To add additional software packages a couple more steps are involved,
+albeit relatively simple.  The thing to understand about the `sagemath/sagemath` image is
+that by default it puts you in a user called `sage`, so in order to install system packages
+it is necessary, when extending the image, to first switch back to the `root` user.
+Then, because the image is based on Ubuntu, the `apt-get` command can be used to install
+Ubuntu packages.  The canonical way to do this in a `Dockerfile` involves updating the
+APT cache, installing the packages, and then cleaning up the APT cache again all within
+a single command (this is in order to keep cache files out of the image):
+
+    USER root
+    RUN apt-get -qq update \
+     && apt-get -qq install -y --no-install-recommends <packages-to-install> \
+     && apt-get -qq clean
+    USER sage
+    
+Finally, just make sure toward the end of the `Dockerfile` that you switch the image
+user back to `sage` (so that when users run the container they are not running it as
+`root`.
+        
+
 Authors
 -------
 
 Nicolas M. Thiéry
+E. Madison Bray
 
 The demo notebooks for GAP, Singular, and Pari were written by the
 authors of the respective kernels. See the