Create a new Hub

Why create a new hub?

The major reasons for making a new hub are:

  1. You wanna use a different kind of authenticator.

  2. Some of your students are admins on another hub, so they can see other students’ work there.

  3. You are running in a different cloud, or using a different billing account.

  4. Your environment is different enough and specialized enough that a different hub is a good idea.

  5. You want a different URL ( vs just

If your reason is something else, it probably needs some justification :)

Setting up a new hub structure

There’s a simple cookiecutter we provide that sets up a blank hub that can be customized.

  1. Make sure you have the cookiecutter python package installed

  2. In the deployments directory, run cookiecutter:

    cookiecutter template/
  3. Answer the questions it asks. Should be fairly basic. It should generate a directory with the name of the hub you provided with a skeleton configuration.

  4. Fill in values for jupyterhub.hub.cookieSecret and jupyterhub.proxy.secretToken on secrets/staging.yaml and secrets/prod.yaml files.

  5. Commit the directory, and make a PR. Once tests pass, merge the PR to get a working staging hub! It should be accessible by an external IP address that you can find with kubectl --namespace=<hub-name>-staging get svc proxy-public.

  6. Make a dns entry for the staging hub (<hub-name>>) pointing to the public IP. Wait to make sure it resolves correctly.

  7. Uncomment the values under jupyterhub.proxy.https under secrets/staging.yaml to enable HTTPS. Run this through CI and make sure HTTPS is set up on the staging hub.

  8. Set up authentication as needed. This should all most likely go under secrets/staging.yaml.

  9. You now need to log into the NFS server, and create a directory owned by 1000:1000 under /export/pool0/homes/_<hubname>. This step doesn’t apply if you are using managed NFS!

  10. User logins should now work in the staging hub. Verify and validate to make sure things are working as they should.

  11. Repeat the process to get the production hub up and running. Tada!