Setting up JupyterHub

Now that we have a Kubernetes cluster and helm setup, we can begin setting up a JupyterHub.

Prepare configuration file

This step prepares a configuration file (config file). We will use the YAML file format to specify JupyterHub’s configuration.

It’s important to save the config file in a safe place. The config file is needed for future changes to JupyterHub’s settings.

For the following steps, use your favorite code editor. We’ll use the nano editor as an example.

  1. Create a file called config.yaml. Using the nano editor, for example, entering nano config.yaml at the terminal will start the editor and open the config file.

  2. Create two random hex strings to use as security tokens. Run these two commands (they’re the same command but run them twice) in a terminal:

    openssl rand -hex 32
openssl rand -hex 32

    Copy the output each time, we’ll use these hex strings in the next step.

  3. Insert these lines into the config.yaml file. When editing YAML files, use straight quotes and spaces and avoid using curly quotes or tabs. Substitute each occurrence of RANDOM_STRING_N below with the output of openssl rand -hex 32. The random hex strings are tokens that will be used to secure your JupyterHub instance (make sure that you keep the quotation marks):

    hub:
  # output of first execution of 'openssl rand -hex 32'
  cookieSecret: "RANDOM_STRING_1"
token:
  # output of second execution of 'openssl rand -hex 32'
  proxy: "RANDOM_STRING_2"

    For example:

    hub:
  cookieSecret: "cb0b45df678709c5cc780ed73690898f7ba0659902f996017296143976ffb97c"
token:
  proxy: "712c4c6c0e78c6c745cfb126f5bbc4b9ba763c78b4bba5797e2eaf508ac99475"

  4. Save the config.yaml file. If using the nano editor, hit Ctrl-X and make sure to answer ‘yes’ when it asks you to save.

Install JupyterHub

  1. Let’s use helm to create the instances that you configured with the config.yaml file. Run this command from the directory that contains the config.yaml file to spin up JupyterHub:

    helm install https://github.com/jupyterhub/helm-chart/releases/download/v0.3.1/jupyterhub-v0.3.1.tgz \
    --name=<YOUR_RELEASE_NAME> \
    --namespace=<YOUR_NAMESPACE> \
    -f config.yaml

    where:

    • --name is an identifier used by helm to refer to this deployment. You need it when you are changing the configuration of this install or deleting it. Use something descriptive that you will easily remember. For a class called data8 you might wish set the name to data8-jupyterhub. In the future you can find out the name by using helm list.

    • --namespace is an identifier used by Kubernetes (among other things) to identify a particular application that might be running on a single Kubernetes cluster. You can install many applications into the same Kubernetes cluster, and each instance of an application is usually separated by being in its own namespace. You’ll need the namespace identifier for performing any commands with kubectl.

    We recommend providing the same value to --name and --namespace for now to avoid too much confusion, but advanced users of Kubernetes and helm should feel free to use different values.

    Note

    If you get a release named <YOUR_CHART> already exists error, then you should delete this helm-chart by running helm delete --purge <YOUR_CHART>. Then reinstall by repeating this step.

  2. While Step 1 is running, you can see the pods being created by entering in a different terminal:

    kubectl --namespace=<YOUR_NAMESPACE> get pod

  3. Wait for the hub and proxy pod to begin running.

  4. You can find the IP to use for accessing the JupyterHub with:

    kubectl --namespace=<YOUR_NAMESPACE> get svc

    The external IP for the proxy-public service should be accessible in a minute or two.

  5. To use JupyterHub, enter the external IP for the proxy-public service in to a browser. JupyterHub is running with a default dummy authenticator so entering any username and password combination will let you enter the hub.

Congratulations! Now that you have JupyterHub running, you can extend it in many ways. You can use a pre-built image for the user container, build your own image, configure different authenticators, and more!