Edit letsencrypt example README

willingc · willingc · commit dd964ade7957 · 2016-10-12T05:13:36.000-07:00
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ 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** include, but are not limited to:
+Possible **use cases** include:
 
 * Creating a JupyterHub demo environment that you can spin up relatively
   quickly.
@@ -31,18 +31,18 @@ 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) 
+
+* **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.
 
@@ -53,47 +53,47 @@ Key components of this reference deployment are:
 
 ### Docker
 
-This deployment uses Docker for all the things, via [Docker Compose](https://docs.docker.com/compose/overview/).
+This deployment uses Docker, via [Docker Compose](https://docs.docker.com/compose/overview/), for all the things.
 [Docker Engine](https://docs.docker.com/engine) 1.12.0 or higher is
-required. Use [Docker's installation instructions](https://docs.docker.com/engine/installation/)
-to set up Docker for your environment. 
-
-To verify your docker installation, whether running docker as a local installation or using [docker-machine](./docs/docker-machine.md), 
-enter these commands:
+required.
 
-```bash
-    docker version
-    docker ps
-```
+1. Use [Docker's installation instructions](https://docs.docker.com/engine/installation/)
+   to set up Docker for your environment.
 
+2. To verify your docker installation, whether running docker as a local
+   installation or using [docker-machine](./docs/docker-machine.md),
+   enter these commands:
 
+   ```bash
+   docker version
+   docker ps
+   ```
 
 ### HTTPS and SSL/TLS certificate
 
-This deployment configures JupyterHub to use HTTPS connections (the 
-default). You must provide TLS certificate chain and key file in the 
-JupyterHub configuration.
+This deployment configures JupyterHub to use HTTPS. You must provide a
+certificate and key file in the JupyterHub configuration. To configure:
 
 1. Obtain the domain name that you wish to use for JupyterHub, for
    example, `myfavoritesite.com` or `jupiterplanet.org`.
 
-1. 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).
+1. If you do not have an existing certificate and key, you can:
 
-1. Copy the certificate chain and key files for the JupyterHub server
-to a directory named `secrets` within this repository directory. 
-These will be added to the JupyterHub Docker image at build time. For
-example, create a `secrets` directory in the root of this repo and 
-copy the certificate and key files (`jupyterhub.crt` and `jupyterhub.key`)
-to this directory:
+   - obtain one from [Let's Encrypt](https://letsencrypt.org) using
+     the [certbot](https://certbot.eff.org) client,
+   - use the helper script in this repo's [letsencrypt example](examples/letsencrypt/README.md), or
+   - [create a self-signed certificate](https://jupyter-notebook.readthedocs.org/en/latest/public_server.html#using-ssl-for-encrypted-communication).
 
-```bash
-    mkdir -p secrets
-    cp jupyterhub.crt jupyterhub.key secrets/
-```
+1. Copy the certificate and key files to a
+   directory named `secrets` in this repository's root directory.  These will be
+   added to the JupyterHub Docker image at build time. For example, create a
+   `secrets` directory in the root of this repo and copy the certificate and
+   key files (`jupyterhub.crt` and `jupyterhub.key`) to this directory:
+
+   ```bash
+   mkdir -p secrets
+   cp jupyterhub.crt jupyterhub.key secrets/
+   ```
 
 
 ## Authenticator setup
@@ -106,30 +106,28 @@ by filling out a form on the GitHub site:
 ![GitHub OAuth application form](docs/oauth-form.png)
 
 In this form, you will specify the OAuth application's callback URL in
-this format:
+this format: `https://<myhost.mydomain>/hub/oauth_callback`.
 
-```
-https://<myhost.mydomain>/hub/oauth_callback
-```
-
-After submitting the GitHub form, your registered GitHub OAuth
-application is assigned a unique Client ID and Client Secret. The 
-Client Secret should be kept private.
+After submitting the GitHub form, your registered GitHub OAuth application is
+assigned a unique Client ID and Client Secret. The Client Secret should be
+kept private.
 
-You must pass the GitHub OAuth Client ID, Client Secret and OAuth
-callback url to JupyterHub at runtime. You can do this by either:
+You must pass the GitHub OAuth Client ID, Client Secret and OAuth callback url
+to JupyterHub at runtime. You can do this by either:
 
 - setting the `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and
-  `OAUTH_CALLBACK_URL` environment variables when you run the 
+  `OAUTH_CALLBACK_URL` environment variables when you run the
   JupyterHub container, or
-- add them to the `.env` file in the root directory of this repository. 
+- add them to the `.env` file in the root directory of this repository.
   For example, update the following lines in the `.env` file:
 
-  **.env**
+  `.env` file
   ```
-        GITHUB_CLIENT_ID=<github_client_id>
-        GITHUB_CLIENT_SECRET=<github_client_secret>
-        OAUTH_CALLBACK_URL=https://<myhost.mydomain>/hub/oauth_callback
+  ...
+  GITHUB_CLIENT_ID=<github_client_id>
+  GITHUB_CLIENT_SECRET=<github_client_secret>
+  OAUTH_CALLBACK_URL=https://<myhost.mydomain>/hub/oauth_callback
+  ...
   ```
 
   **Note:** The `.env` file is a special file that Docker Compose uses
@@ -141,25 +139,30 @@ callback url to JupyterHub at runtime. You can do this by either:
 
 ## Build the JupyterHub Docker image
 
-Configure JupyterHub 
+Configure JupyterHub and build it into a Docker image.
 
-and build it into a Docker image.
+1. Create a `userlist` file with a list of authorized users. The list should
+   contain GitHub usernames, and this file should designate at least one
+   `admin` user. For instance, this example file contains three users,
+   `jtyberg`, `jenny`, and `guido`, and one designated administrator,
+   `jtyberg`:
 
-1. Create a `userlist` file with a list of authorized users.  At a minimum, this file should contain a single admin user.  The username should be a GitHub username.  For example:
-
-**file**
-```
+   `userlist` file
+   ```
    jtyberg admin
-```
+   jenny
+   guido
+   ```
 
-   The admin user will have the ability to add more users in the JupyterHub admin console.
+   The admin user will have the ability to add more users through JupyterHub's
+   admin console.
 
-1. Use [docker-compose](https://docs.docker.com/compose/reference/) to build the
-   JupyterHub Docker image on the active Docker machine host:
+1. Use [docker-compose](https://docs.docker.com/compose/reference/) to build
+   the JupyterHub Docker image on the active Docker machine host:
 
-```bash
-    make build
-```
+   ```bash
+   make build
+   ```
 
 
 ## Spawner: Prepare the Jupyter Notebook Image
diff --git a/examples/letsencrypt/README.md b/examples/letsencrypt/README.md
@@ -1,14 +1,23 @@
 # Let's Encrypt
 
-This example includes a Docker Compose configuration file that you can use to deploy [JupyterHub](https://github.com/jupyter/jupyterhub) with TLS certificate and key files generated by [Let's Encrypt](https://letsencrypt.org).
+This example includes a Docker Compose configuration file that you can
+use to deploy [JupyterHub](https://github.com/jupyter/jupyterhub) with
+TLS certificate and key files generated by [Let's Encrypt](https://letsencrypt.org).
 
-The `docker-compose.yml` configuration file in this example extends the JupyterHub service defined in the `docker-compose.yml` file in the root directory of this repository.  
+The `docker-compose.yml` configuration file in this example extends the
+JupyterHub service defined in the `docker-compose.yml` file in the root
+directory of this repository.  
 
-When you run the JupyterHub Docker container using the configuration file in this directory, Docker mounts an additional volume containing the Let's Encrypt TLS certificate and key files, and overrides the `SSL_CERT` and `SSL_KEY` environment variables to point to these files.
+When you run the JupyterHub Docker container using the configuration
+file in this directory, Docker mounts an additional volume containing
+the Let's Encrypt TLS certificate and key files, and overrides the
+`SSL_CERT` and `SSL_KEY` environment variables to point to these files.
 
 ## Create a secrets volume
 
-This example stores the Let's Encrypt TLS certificate and key files in a Docker volume, and mounts the volume to the JupyterHub container at runtime.  
+This example stores the Let's Encrypt TLS certificate and key files in
+a Docker volume, and mounts the volume to the JupyterHub container at
+runtime.  
 
 Create a volume to store the certificate and key files.
 
@@ -21,11 +30,18 @@ docker volume create --name jupyterhub-secrets
 
 ## Generate Let's Encrypt certificate and key
 
-Run the `letsencrypt.sh` script to create a TLS full-chain certificate and key.  
+Run the `letsencrypt.sh` script to create a TLS full-chain certificate
+and key.  
 
-The script downloads and runs the `letsencrypt` Docker image to create a full-chain certificate and private key, and stores the files in a Docker volume.  You must provide a valid, routable, fully-qualified domain name (you must own it), and you must activate the Docker machine host that the domain points to before you run this script.  You must also provide a valid email address and the name of the volume you created above.
+The script downloads and runs the `letsencrypt` Docker image to create a
+full-chain certificate and private key, and stores the files in a Docker
+volume.  You must provide a valid, routable, fully-qualified domain name (you
+must own it), and you must activate the Docker machine host that the domain
+points to before you run this script.  You must also provide a valid email
+address and the name of the volume you created above.
 
-_Notes:_ The script hard codes several `letsencrypt` options, one of which automatically agrees to the Let's Encrypt Terms of Service.
+_Notes:_ The script hard codes several `letsencrypt` options, one of which
+automatically agrees to the Let's Encrypt Terms of Service.
 
 ```
 # Activate Docker machine where JupyterHub will run
@@ -39,7 +55,11 @@ eval "$(docker-machine env jupyterhub)"
 
 ## Run JupyterHub container
 
-To run the JupyterHub container using the Let's Encrypt certificate and key, set the `SECRETS_VOLUME` environment variable to the name of the Docker volume containing the certificate and key files, and run `docker-compose` **from the root directory** of this repository while specifying the `docker-compose.yml` configuration in this directory:
+To run the JupyterHub container using the Let's Encrypt certificate and key,
+set the `SECRETS_VOLUME` environment variable to the name of the Docker volume
+containing the certificate and key files, and run `docker-compose` **from the
+root directory** of this repository while specifying the `docker-compose.yml`
+configuration in this directory:
 
 ```
 export SECRETS_VOLUME=jupyterhub-secrets
