Edit intro, tech overview, prerequisites

Author: willingc

README.md

@@ -1,50 +1,81 @@
-# jupyterhub-deploy-docker
-
-This repository provides a reference deployment of [JupyterHub](https://github.com/jupyter/jupyterhub), a multi-user [Jupyter Notebook](http://jupyter.org/) environment, on a **single host** using [Docker](https://docs.docker.com).  
-
-This deployment:
-
-* Runs the [JupyterHub components](https://jupyterhub.readthedocs.org/en/latest/getting-started.html#overview) in a Docker container on the host
-* Uses [DockerSpawner](https://github.com/jupyter/dockerspawner) to spawn single-user Jupyter Notebook servers in separate Docker containers on the same host
-* Persists JupyterHub data in a Docker volume on the host
-* Persists user notebook directories in Docker volumes on the host
-* Uses [OAuthenticator](https://github.com/jupyter/oauthenticator) and [GitHub OAuth](https://developer.github.com/v3/oauth/) to authenticate users
+**[Technical Overview](#technical-overview)** |
+**[Prerequisites](#prerequisites)** |
+**[Authenticator setup](#authenticator-setup)** |
+**[Build the JupyterHub Docker image](#build-the-jupyterhub-docker-image)** |
+**[Spawner: Prepare the Jupyter Notebook Image](#spawner-prepare-the-jupyter-notebook-image)** |
+**[Run JupyterHub](#run-jupyterhub)** |
+**[Behind the scenes](#behind-the-scenes)** |
+**[FAQ](#faq)**
 
-![JupyterHub single host Docker deployment](internal/jupyterhub-docker.png)
+# jupyterhub-deploy-docker
 
-## Use Cases
+The **jupyterhub-deploy-docker** repository provides a reference
+deployment of [JupyterHub](https://github.com/jupyter/jupyterhub), a
+multi-user [Jupyter Notebook](http://jupyter.org/) environment, on a
+**single host** using [Docker](https://docs.docker.com).  
 
-Possible use cases for this deployment may include, but are not limited to:
+Possible **use cases** for this deployment may include, but are not
+limited to:
 
 * A JupyterHub demo environment that you can spin up relatively quickly.
-* A multi-user Jupyter Notebook environment for small classes, teams, or departments.
+* A multi-user Jupyter Notebook environment for small classes, teams,
+  or departments.
+
+**Disclaimer:** This deployment is **NOT** intended for a production
+environment.  
+
+
+## Technical Overview
+
+Key components of this reference deployment are:
+
+* **Host**: Runs the [JupyterHub components](https://jupyterhub.readthedocs.org/en/latest/getting-started.html#overview)
+  in a Docker container on the host.
+  
+* **Authenticator**: Uses [OAuthenticator](https://github.com/jupyter/oauthenticator)
+  and [GitHub OAuth](https://developer.github.com/v3/oauth/) to
+  authenticate users.
+  
+* **Spawner**:Uses [DockerSpawner](https://github.com/jupyter/dockerspawner) 
+  to spawn single-user Jupyter Notebook servers in separate Docker
+  containers on the same host.
+  
+* **Persistence of Hub data**: Persists JupyterHub data in a Docker
+  volume on the host.
+  
+* **Persistence of user notebook directories**: Persists user notebook
+  directories in Docker volumes on the host.
 
-## Disclaimer
+![JupyterHub single host Docker deployment](internal/jupyterhub-docker.png)
 
-This deployment is **NOT** intended for a production environment.  
 
 ## Prerequisites
 
-* This deployment uses Docker for all the things, via  [Docker Compose](https://docs.docker.com/compose/overview/).
-  It requires [Docker Engine](https://docs.docker.com/engine) 1.12.0 or higher.
-  See the [installation instructions](https://docs.docker.com/engine/installation/) for your environment.
-* This example configures JupyterHub for HTTPS connections (the default).
-   As such, you must provide TLS certificate chain and key files to the JupyterHub server.
-   If you do not have your own certificate chain and key, you can either
-   [create self-signed versions](https://jupyter-notebook.readthedocs.org/en/latest/public_server.html#using-ssl-for-encrypted-communication),
-   or obtain real ones from [Let's Encrypt](https://letsencrypt.org)
-   (see the [letsencrypt example](examples/letsencrypt/README.md) for instructions).
-
-From here on, we'll assume you are set up with docker,
-via a local installation or [docker-machine](./docs/docker-machine.md).
-At this point,
-
+* **Docker**: This deployment uses Docker for all the things, via 
+  [Docker Compose](https://docs.docker.com/compose/overview/). It
+  requires [Docker Engine](https://docs.docker.com/engine) 1.12.0 or
+  higher. Use the [Docker installation instructions](https://docs.docker.com/engine/installation/)
+  for your environment.
+  
+* **HTTPS and SSL**: This deployment configures JupyterHub to use HTTPS
+  connections (the default). You must provide TLS certificate chain and
+  key files in the JupyterHub configuration. If you do not have an
+  existing certificate chain and key, you can [create self-signed versions](https://jupyter-notebook.readthedocs.org/en/latest/public_server.html#using-ssl-for-encrypted-communication),
+  or obtain real ones from [Let's Encrypt](https://letsencrypt.org)
+  (see the [letsencrypt example](examples/letsencrypt/README.md) for
+  instructions).
+
+To verify that you are set up with docker, via a local installation or
+[docker-machine](./docs/docker-machine.md), run:
+
+```bash
     docker ps
+```
 
-should work.
+This command will return running Docker processes.
 
 
-## Setup GitHub Authentication
+## Authenticator setup
 
 This deployment uses GitHub OAuth to authenticate users.
 It requires that you create a [GitHub application](https://github.com/settings/applications/new).
@@ -70,6 +101,7 @@ If you choose to place the GitHub secrets in this file,
 you should ensure that this file remains private
 (e.g., do not commit the secrets to source control).
 
+
 ## Build the JupyterHub Docker image
 
 Configure JupyterHub and build it into a Docker image.
@@ -96,7 +128,8 @@ Configure JupyterHub and build it into a Docker image.
     make build
     ```
 
-## Prepare the Jupyter Notebook Image
+
+## Spawner: Prepare the Jupyter Notebook Image
 
 You can configure JupyterHub to spawn Notebook servers from any Docker image, as
 long as the image's `ENTRYPOINT` and/or `CMD` starts a single-user instance of
@@ -130,6 +163,7 @@ You can pull the image using the following command:
 make notebook_image
 ```
 
+
 ## Run JupyterHub
 
 Run the JupyterHub container on the host.
@@ -152,6 +186,8 @@ To bring down the JupyterHub container:
 docker-compose down
 ```
 
+---
+
 ## Behind the scenes
 
 `make build` does a few things behind the scenes, to set up the environment for JupyterHub:
@@ -177,6 +213,8 @@ Create a Docker volume to persist JupyterHub data.   This volume will reside on
 docker volume create --name jupyterhub-data
 ```
 
+---
+
 ## FAQ
 
 ### How can I view the logs for JupyterHub or users' Notebook servers?