From d99aa826429b42ed8014fe8eacdcfe5d28400c07 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Tue, 11 Oct 2016 20:58:14 -0700 Subject: [PATCH] Edit intro, tech overview, prerequisites --- README.md | 102 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index dfdfeda..0a7c15d 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,81 @@ +**[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-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). +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). -This deployment: +Possible **use cases** for this deployment may include, but are not +limited to: -* 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 +* A JupyterHub demo environment that you can spin up relatively quickly. +* 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. ![JupyterHub single host Docker deployment](internal/jupyterhub-docker.png) -## Use Cases - -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. - -## Disclaimer - -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). +* **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). -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, +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?