jupyterhub-deploy-docker/examples/letsencrypt

Let's Encrypt

This example includes a Docker Compose configuration file that you can use to deploy JupyterHub with TLS certificate and key files generated by Let's Encrypt.

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.

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.

Create a volume to store the certificate and key files.

# Activate Docker machine where JupyterHub will run
eval "$(docker-machine env jupyterhub)"

docker volume create --name jupyterhub-secrets

Generate Let's Encrypt 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.

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
eval "$(docker-machine env jupyterhub)"

./letsencrypt.sh \
  --domain myhost.mydomain \
  --email me@mydomain \
  --volume jupyterhub-secrets

Run JupyterHub container

To run the JupyterHub container using the configuration in this directory, run the hub.sh script from the root directory of this repository and specify the docker-compose.yml file in this directory. Set the SECRETS_VOLUME environment variable to the name of the Docker volume containing the TLS certificate and key files.

SECRETS_VOLUME=jupyterhub-secrets \
  ./hub.sh -f examples/letsencrypt/docker-compose.yml up -d