Edit intro, tech overview, prerequisites
This commit is contained in:
Carol Willing
parent
3c3b507caf
commit
d99aa82642
102
README.md
102
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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
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,
|
||||
* **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?
|
||||
|
||||
Loading…
Reference in New Issue
Block a user