Cheatsheet: Setting up JupyterHub

Prepare configuration file config.yaml

  1. Create a file called config.yaml.

  2. Create two random hex strings to use as security tokens:

    openssl rand -hex 32
    openssl rand -hex 32
  3. Insert these lines into the config.yaml file. Substitute each occurrence of RANDOM_STRING_N below with the output of openssl rand -hex 32.

    config.yaml file

      # output of first execution of 'openssl rand -hex 32'
      cookieSecret: "RANDOM_STRING_1"
      # output of second execution of 'openssl rand -hex 32'
      secretToken: "RANDOM_STRING_2"
  4. Save the config.yaml file.

Install JupyterHub

  1. From terminal:

    # add jupyterhub helm repository
    helm repo add jupyterhub
    helm repo update
    # install chart
    helm install jupyterhub/jupyterhub \
        --version=v0.4 \
        --name=<YOUR-RELEASE-NAME> \
        --namespace=<YOUR-NAMESPACE> \
        -f config.yaml
    # check hub and proxy pods are running
    kubectl --namespace=<YOUR_NAMESPACE> get pod
    # find IP to access JupyterHub (external IP for proxy-public service)
    kubectl --namespace=<YOUR_NAMESPACE> get svc
    # alternative verbose command for IP
    # kubectl --namespace=<YOUR_NAMESPACE> describe svc proxy-public
  2. To use JupyterHub:

    • enter external IP for the proxy-public service into a browser.
    • entering any username and password combination as JupyterHub is running with a default dummy authenticator


  • --name For a class called data8 you might wish set the name to data8-jupyterhub. Find out the name by using helm list.
  • --namespace is to identify a particular application
  • We recommend using the same value for --name and --namespace
  • If you get a release exists error, then helm delete --purge <YOUR-RELEASE-NAME>. Reinstall by repeating this step. If it persists, kubectl delete <YOUR-NAMESPACE> and try again.
  • If you get a time out error, add a --timeout=SOME-LARGE-NUMBER parameter to the helm install command.