This guide documents the tasks associated with installing and configuring "The Littlest Jupyterhub" (TLJH) on Nimbus. It is assumed that you have already created an instance and are able to log on to it using ssh. The developer documentation for TLJH is available at  https://the-littlest-jupyterhub.readthedocs.io/en/latest/install/custom-server.html. 

Set up networking

Jupyterhub will require the standard HTTPS port and we also want to redirect HTTP to HTTPS, so we need to open these ports:

• From your Nimbus dashboard, under the "Network" section of the left-hand navigation bar, select "Security Groups", then click on "Create Security Group" on the right hand side:
  • Name: give it a meaningful name (e.g. jupyterhub)
  • Description: open ports to allow Jupyterhub to communicate

  Once created, click on "Manage Rules" for that security group, then click on "Add Rule" in the top right, click Rule and then select HTTP from the drop-down menu. 

• Repeat for HTTPS, then it should look like this:
  
  
• Under the "Compute" section of the left-hand bar, select "Instances", click the Actions menu to the right of your instance, then "Edit Security Groups" and add the "jupyterhub" security group.
  

Install TLJH

1. ssh into the instance and check if Python 3, curl, and git are installed using the following command (should be installed by default with latest Ubuntu):

   apt list python3 git curl

2. Download and run the installer using the following code, making sure to replace <admin username> with the username of the account that will act as adminstrator. If you have yet to create any accounts on the VM simply use "ubuntu". This process will take approximately 25 minutes.

   curl https://raw.githubusercontent.com/jupyterhub/the-littlest-jupyterhub/master/bootstrap/bootstrap.py | sudo -E python3 - --admin  <admin username>

3. If everything runs as it should you'll see the following output with the final message being "Done!"

   

4. You can then access the jupyterhub from the public IP associated with your instance, for eg. http://146.118.66.157, and you should see the sign-in page shown below. Note we will resolve the security warning next. If you fail to connect to the jupyterhub check that the security group created in the network setup section has been added to your instance.
   

Enable HTTPS for secure communication

In order to set up HTTPS using TLJH and Lets encrypt you need a domain name for your hub. You may be able to arrange one with your institution, however if you just want a free and easy solution you can use a DNS service provider. Dynu is free, has a good selection of features, no pesky reminders to register every month, and great documentation. See below for an example of my DNS control panel:

Once you have a domain name configured, set it in TLJH:

1. Modify the TLJH config:

   sudo tljh-config set https.enabled true
   sudo tljh-config set https.letsencrypt.email you@example.com
   sudo tljh-config add-item https.letsencrypt.domains yourhub.yourdomain.edu

   replacing you@example.com with your email address and yourhub.yourdomain.edu with your domain name.

2. You can check your config file with 

   sudo tljh-config show

3. Then reload the proxy to load the new configuration

   sudo tljh-config reload proxy

At this point, the proxy should negotiate with Let’s Encrypt to set up a trusted HTTPS certificate for you. It may take a moment for the proxy to negotiate with Let’s Encrypt to get your certificates, after which you can access your Hub securely at https://yourhub.yourdomain.edu.

September 2021 security update

An old DST Root CA X3 certificate expires on 2021-09-30, and this is used to sign part of the Let's Encrypt certificate chain. This is in addition to another root certificate which is not due to expire. As a result, in some cases the OpenSSL 1.0.2 version will regard the certificates issued by the Let’s Encrypt CA as having an expired trust chain. If you believe you may be affected, you should read https://www.openssl.org/blog/blog/2021/09/13/LetsEncryptRootCertExpire/ for more information.