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

Edit letsencrypt example README

Browse Source
This commit is contained in:
Carol Willing 2016-10-12 05:13:36 -07:00
parent ccd512c6ea
commit dd964ade79
2 changed files with 94 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
README.md
View File

@ -14,7 +14,7 @@ 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** include, but are not limited to: Possible **use cases** include:
* Creating a JupyterHub demo environment that you can spin up relatively * Creating a JupyterHub demo environment that you can spin up relatively
quickly. quickly.
@ -53,12 +53,15 @@ Key components of this reference deployment are:
### Docker ### 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 [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/) required.
1. Use [Docker's installation instructions](https://docs.docker.com/engine/installation/)
to set up Docker for your environment. 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), 2. To verify your docker installation, whether running docker as a local
installation or using [docker-machine](./docs/docker-machine.md),
enter these commands: enter these commands:
```bash ```bash
@ -66,29 +69,26 @@ enter these commands:
docker ps docker ps
``` ```
### HTTPS and SSL/TLS certificate ### HTTPS and SSL/TLS certificate
This deployment configures JupyterHub to use HTTPS connections (the This deployment configures JupyterHub to use HTTPS. You must provide a
default). You must provide TLS certificate chain and key file in the certificate and key file in the JupyterHub configuration. To configure:
JupyterHub configuration.
1. Obtain the domain name that you wish to use for JupyterHub, for 1. Obtain the domain name that you wish to use for JupyterHub, for
example, `myfavoritesite.com` or `jupiterplanet.org`. example, `myfavoritesite.com` or `jupiterplanet.org`.
1. If you do not have an existing certificate chain and key, you can 1. If you do not have an existing certificate 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 - obtain one from [Let's Encrypt](https://letsencrypt.org) using
to a directory named `secrets` within this repository directory. the [certbot](https://certbot.eff.org) client,
These will be added to the JupyterHub Docker image at build time. For - use the helper script in this repo's [letsencrypt example](examples/letsencrypt/README.md), or
example, create a `secrets` directory in the root of this repo and - [create a self-signed certificate](https://jupyter-notebook.readthedocs.org/en/latest/public_server.html#using-ssl-for-encrypted-communication).
copy the certificate and key files (`jupyterhub.crt` and `jupyterhub.key`)
to this directory: 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 ```bash
mkdir -p secrets mkdir -p secrets
@ -106,18 +106,14 @@ by filling out a form on the GitHub site:
![GitHub OAuth application form](docs/oauth-form.png) ![GitHub OAuth application form](docs/oauth-form.png)
In this form, you will specify the OAuth application's callback URL in In this form, you will specify the OAuth application's callback URL in
this format: this format: `https://<myhost.mydomain>/hub/oauth_callback`.
``` After submitting the GitHub form, your registered GitHub OAuth application is
https://<myhost.mydomain>/hub/oauth_callback assigned a unique Client ID and Client Secret. The Client Secret should be
``` kept private.
After submitting the GitHub form, your registered GitHub OAuth You must pass the GitHub OAuth Client ID, Client Secret and OAuth callback url
application is assigned a unique Client ID and Client Secret. The to JupyterHub at runtime. You can do this by either:
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:
- setting the `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and - 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
@ -125,11 +121,13 @@ callback url to JupyterHub at runtime. You can do this by either:
- 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: For example, update the following lines in the `.env` file:
**.env** `.env` file
``` ```
...
GITHUB_CLIENT_ID=<github_client_id> GITHUB_CLIENT_ID=<github_client_id>
GITHUB_CLIENT_SECRET=<github_client_secret> GITHUB_CLIENT_SECRET=<github_client_secret>
OAUTH_CALLBACK_URL=https://<myhost.mydomain>/hub/oauth_callback OAUTH_CALLBACK_URL=https://<myhost.mydomain>/hub/oauth_callback
...
``` ```
**Note:** The `.env` file is a special file that Docker Compose uses **Note:** The `.env` file is a special file that Docker Compose uses
@ -141,21 +139,26 @@ callback url to JupyterHub at runtime. You can do this by either:
## Build the JupyterHub Docker image ## 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: `userlist` file
**file**
``` ```
jtyberg admin 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 1. Use [docker-compose](https://docs.docker.com/compose/reference/) to build
JupyterHub Docker image on the active Docker machine host: the JupyterHub Docker image on the active Docker machine host:
```bash ```bash
make build make build

36
examples/letsencrypt/README.md
View File

@ -1,14 +1,23 @@
# Let's Encrypt # 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 ## 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. 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 ## 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 # Activate Docker machine where JupyterHub will run
@ -39,7 +55,11 @@ eval "$(docker-machine env jupyterhub)"
## Run JupyterHub container ## 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 export SECRETS_VOLUME=jupyterhub-secrets