mm/jupyterhub-deploy-docker
1
0
Fork 0
Code Pull Requests Releases Activity

Edit intro, tech overview, prerequisites

Browse Source
This commit is contained in:
Carol Willing 2016-10-11 20:58:14 -07:00
parent 3c3b507caf
commit d99aa82642
1 changed files with 70 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@ -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 # 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 * A JupyterHub demo environment that you can spin up relatively quickly.
* Uses [DockerSpawner](https://github.com/jupyter/dockerspawner) to spawn single-user Jupyter Notebook servers in separate Docker containers on the same host * A multi-user Jupyter Notebook environment for small classes, teams,
* Persists JupyterHub data in a Docker volume on the host or departments.
* 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 **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) ![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 ## Prerequisites
* This deployment uses Docker for all the things, via [Docker Compose](https://docs.docker.com/compose/overview/). * **Docker**: This deployment uses Docker for all the things, via
It requires [Docker Engine](https://docs.docker.com/engine) 1.12.0 or higher. [Docker Compose](https://docs.docker.com/compose/overview/). It
See the [installation instructions](https://docs.docker.com/engine/installation/) for your environment. requires [Docker Engine](https://docs.docker.com/engine) 1.12.0 or
* This example configures JupyterHub for HTTPS connections (the default). higher. Use the [Docker installation instructions](https://docs.docker.com/engine/installation/)
As such, you must provide TLS certificate chain and key files to the JupyterHub server. for your environment.
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), * **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) or obtain real ones from [Let's Encrypt](https://letsencrypt.org)
(see the [letsencrypt example](examples/letsencrypt/README.md) for instructions). (see the [letsencrypt example](examples/letsencrypt/README.md) for
instructions).
From here on, we'll assume you are set up with docker, To verify that you are set up with docker, via a local installation or
via a local installation or [docker-machine](./docs/docker-machine.md). [docker-machine](./docs/docker-machine.md), run:
At this point,
```bash
docker ps docker ps
```
should work. This command will return running Docker processes.
## Setup GitHub Authentication ## Authenticator setup
This deployment uses GitHub OAuth to authenticate users. This deployment uses GitHub OAuth to authenticate users.
It requires that you create a [GitHub application](https://github.com/settings/applications/new). 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 you should ensure that this file remains private
(e.g., do not commit the secrets to source control). (e.g., do not commit the secrets to source control).
## Build the JupyterHub Docker image ## Build the JupyterHub Docker image
Configure JupyterHub and build it into a 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 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 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 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 make notebook_image
``` ```
## Run JupyterHub ## Run JupyterHub
Run the JupyterHub container on the host. Run the JupyterHub container on the host.
@ -152,6 +186,8 @@ To bring down the JupyterHub container:
docker-compose down docker-compose down
``` ```
---
## Behind the scenes ## Behind the scenes
`make build` does a few things behind the scenes, to set up the environment for JupyterHub: `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 docker volume create --name jupyterhub-data
``` ```
---
## FAQ ## FAQ
### How can I view the logs for JupyterHub or users' Notebook servers? ### How can I view the logs for JupyterHub or users' Notebook servers?