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

Edit prerequisites and OAuth

Browse Source
This commit is contained in:
Carol Willing 2016-10-11 23:23:17 -07:00
parent d99aa82642
commit ccd512c6ea
2 changed files with 107 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
README.md
View File

@ -9,17 +9,17 @@
# jupyterhub-deploy-docker # jupyterhub-deploy-docker
The **jupyterhub-deploy-docker** repository provides a reference **jupyterhub-deploy-docker** provides a reference
deployment of [JupyterHub](https://github.com/jupyter/jupyterhub), a deployment of [JupyterHub](https://github.com/jupyter/jupyterhub), a
multi-user [Jupyter Notebook](http://jupyter.org/) environment, on a multi-user [Jupyter Notebook](http://jupyter.org/) environment, on a
**single host** using [Docker](https://docs.docker.com). **single host** using [Docker](https://docs.docker.com).
Possible **use cases** for this deployment may include, but are not Possible **use cases** include, but are not limited to:
limited to:
* A JupyterHub demo environment that you can spin up relatively quickly. * Creating a JupyterHub demo environment that you can spin up relatively
* A multi-user Jupyter Notebook environment for small classes, teams, quickly.
or departments. * Providing a multi-user Jupyter Notebook environment for small classes,
teams, or departments.
**Disclaimer:** This deployment is **NOT** intended for a production **Disclaimer:** This deployment is **NOT** intended for a production
environment. environment.
@ -51,82 +51,115 @@ Key components of this reference deployment are:
## Prerequisites ## Prerequisites
* **Docker**: This deployment uses Docker for all the things, via ### Docker
[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 This deployment uses Docker for all the things, via [Docker Compose](https://docs.docker.com/compose/overview/).
connections (the default). You must provide TLS certificate chain and [Docker Engine](https://docs.docker.com/engine) 1.12.0 or higher is
key files in the JupyterHub configuration. If you do not have an required. Use [Docker's installation instructions](https://docs.docker.com/engine/installation/)
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), to set up Docker for your environment.
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 To verify your docker installation, whether running docker as a local installation or using [docker-machine](./docs/docker-machine.md),
[docker-machine](./docs/docker-machine.md), run: enter these commands:
```bash ```bash
docker version
docker ps docker ps
``` ```
This command will return running Docker processes.
### 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.
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. 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:
```bash
mkdir -p secrets
cp jupyterhub.crt jupyterhub.key secrets/
```
## Authenticator setup ## 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).
You will need to specify an OAuth callback URL in the following form: It requires that you create and register a [GitHub OAuth application](https://github.com/settings/applications/new)
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:
``` ```
https://<myhost.mydomain>/hub/oauth_callback https://<myhost.mydomain>/hub/oauth_callback
``` ```
You must pass the secrets that GitHub provides for your application to JupyterHub at runtime. After submitting the GitHub form, your registered GitHub OAuth
You can do this by setting the `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, application is assigned a unique Client ID and Client Secret. The
and `OAUTH_CALLBACK_URL` environment variables when you run the JupyterHub container, Client Secret should be kept private.
or you can add them to the `.env` file in the root directory of this repository. For example,
``` You must pass the GitHub OAuth Client ID, Client Secret and OAuth
GITHUB_CLIENT_ID=<github_client_id> callback url to JupyterHub at runtime. You can do this by either:
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 to lookup environment variables. - setting the `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and
If you choose to place the GitHub secrets in this file, `OAUTH_CALLBACK_URL` environment variables when you run the
you should ensure that this file remains private JupyterHub container, or
(e.g., do not commit the secrets to source control). - add them to the `.env` file in the root directory of this repository.
For example, update the following lines in the `.env` file:
**.env**
```
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
to lookup environment variables. If you choose to place the GitHub
OAuth application settings in this file, you should make sure that the
file remains private (be careful to not commit the `.env` file with
these 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
1. Copy the TLS 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. If you do not have a 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). and build it into a Docker image.
```
mkdir -p secrets
cp jupyterhub.crt jupyterhub.key secrets/
```
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: 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**
```
jtyberg admin jtyberg admin
``` ```
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 in the JupyterHub admin console.
1. Use [docker-compose](https://docs.docker.com/compose/reference/) to build the 1. Use [docker-compose](https://docs.docker.com/compose/reference/) to build the
JupyterHub Docker image on the active Docker machine host: JupyterHub Docker image on the active Docker machine host:
``` ```bash
make build make build
``` ```
## Spawner: Prepare the Jupyter Notebook Image ## Spawner: Prepare the Jupyter Notebook Image
@ -159,7 +192,7 @@ Notebook server that is compatible with JupyterHub).
You can pull the image using the following command: You can pull the image using the following command:
``` ```bash
make notebook_image make notebook_image
``` ```
@ -170,19 +203,20 @@ Run the JupyterHub container on the host.
To run the JupyterHub container in detached mode: To run the JupyterHub container in detached mode:
``` ```bash
docker-compose up -d docker-compose up -d
``` ```
Once the container is running, you should be able to access the JupyterHub console at Once the container is running, you should be able to access the JupyterHub console at
**file**
``` ```
https://myhost.mydomain https://myhost.mydomain
``` ```
To bring down the JupyterHub container: To bring down the JupyterHub container:
``` ```bash
docker-compose down docker-compose down
``` ```
@ -192,6 +226,14 @@ docker-compose down
`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:
### Create a JupyterHub Data Volume
Create a Docker volume to persist JupyterHub data. This volume will reside on the host machine. Using a volume allows user lists, cookies, etc., to persist across JupyterHub container restarts.
```bash
docker volume create --name jupyterhub-data
```
### Create a Docker Network ### Create a Docker Network
Create a Docker network for inter-container communication. The benefits of using a Docker network are: Create a Docker network for inter-container communication. The benefits of using a Docker network are:
@ -201,18 +243,10 @@ Create a Docker network for inter-container communication. The benefits of usin
Here we create a Docker network named `jupyterhub-network`. Later, we will configure the JupyterHub and single-user Jupyter Notebook containers to run attached to this network. Here we create a Docker network named `jupyterhub-network`. Later, we will configure the JupyterHub and single-user Jupyter Notebook containers to run attached to this network.
``` ```bash
docker network create jupyterhub-network docker network create jupyterhub-network
``` ```
### Create a JupyterHub Data Volume
Create a Docker volume to persist JupyterHub data. This volume will reside on the host machine. Using a volume allows user lists, cookies, etc., to persist across JupyterHub container restarts.
```
docker volume create --name jupyterhub-data
```
--- ---
## FAQ ## FAQ
@ -221,7 +255,7 @@ docker volume create --name jupyterhub-data
Use `docker logs <container>`. For example, to view the logs of the `jupyterhub` container Use `docker logs <container>`. For example, to view the logs of the `jupyterhub` container
``` ```bash
docker logs jupyterhub docker logs jupyterhub
``` ```
@ -235,7 +269,7 @@ JupyterHub reads the Notebook image name from `jupyterhub_config.py`, which
reads the Notebook image name from the `DOCKER_NOTEBOOK_IMAGE` environment reads the Notebook image name from the `DOCKER_NOTEBOOK_IMAGE` environment
variable: variable:
``` ```python
# DockerSpawner setting in jupyterhub_config.py # DockerSpawner setting in jupyterhub_config.py
c.DockerSpawner.container_image = os.environ['DOCKER_NOTEBOOK_IMAGE'] c.DockerSpawner.container_image = os.environ['DOCKER_NOTEBOOK_IMAGE']
``` ```
@ -243,6 +277,7 @@ c.DockerSpawner.container_image = os.environ['DOCKER_NOTEBOOK_IMAGE']
By default, the`DOCKER_NOTEBOOK_IMAGE` environment variable is set in the By default, the`DOCKER_NOTEBOOK_IMAGE` environment variable is set in the
`.env` file. `.env` file.
**file**
``` ```
# Setting in the .env file # Setting in the .env file
DOCKER_NOTEBOOK_IMAGE=jupyter/scipy-notebook:2d878db5cbff DOCKER_NOTEBOOK_IMAGE=jupyter/scipy-notebook:2d878db5cbff
@ -254,7 +289,7 @@ by setting the `DOCKER_NOTEBOOK_IMAGE` variable to a different Notebook
image in the environment where you launch JupyterHub. For example, the image in the environment where you launch JupyterHub. For example, the
following setting would be used to spawn single-user `pyspark` notebook servers: following setting would be used to spawn single-user `pyspark` notebook servers:
``` ```bash
export DOCKER_NOTEBOOK_IMAGE=jupyterhub/pyspark-notebook:2d878db5cbff export DOCKER_NOTEBOOK_IMAGE=jupyterhub/pyspark-notebook:2d878db5cbff
docker-compose up -d docker-compose up -d
@ -282,25 +317,25 @@ There are multiple ways to [backup and restore](https://docs.docker.com/engine/u
Suppose you have the following running containers: Suppose you have the following running containers:
``` ```bash
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Names}}" docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Names}}"
CONTAINER ID IMAGE NAMES CONTAINER ID IMAGE NAMES
bc02dd6bb91b jupyter/minimal-notebook jupyter-jtyberg bc02dd6bb91b jupyter/minimal-notebook jupyter-jtyberg
7b48a0b33389 jupyterhub jupyterhub 7b48a0b33389 jupyterhub jupyterhub
``` ```
In this deployment, the user's notebook directories (`/home/jovyan/work`) are backed by Docker volumes. In this deployment, the user's notebook directories (`/home/jovyan/work`) are backed by Docker volumes.
``` ```bash
docker inspect -f '{{ .Mounts }}' jupyter-jtyberg docker inspect -f '{{ .Mounts }}' jupyter-jtyberg
[{jtyberg /var/lib/docker/volumes/jtyberg/_data /home/jovyan/work local rw true rprivate}] [{jtyberg /var/lib/docker/volumes/jtyberg/_data /home/jovyan/work local rw true rprivate}]
``` ```
We can backup the user's notebook directory by running a separate container that mounts the user's volume and creates a tarball of the directory. We can backup the user's notebook directory by running a separate container that mounts the user's volume and creates a tarball of the directory.
``` ```bash
docker run --rm \ docker run --rm \
-u root \ -u root \
-v /tmp:/backups \ -v /tmp:/backups \

BIN
docs/oauth-form.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 244 KiB