Enable HTTPS

Every JupyterHub deployment should enable HTTPS!

HTTPS encrypts traffic so that usernames, passwords and your data are communicated securely. sensitive bits of information are communicated securely. The Littlest JupyterHub supports automatically configuring HTTPS via Let’s Encrypt, or setting it up manually with your own TLS key and certificate. Unless you have a strong reason to use the manual method, you should use the Let’s Encrypt method.

Note

You must have a domain name set up to point to the IP address on which TLJH is accessible before you can set up HTTPS.

Automatic HTTPS with Let’s Encrypt

Note

If the machine you are running on is not reachable from the internet - for example, if it is a machine internal to your organization that is cut off from the internet - you can not use this method. Please set up a DNS entry and HTTPS manually.

To enable HTTPS via letsencrypt:

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

where you@example.com is your email address and yourhub.yourdomain.edu is the domain where your hub will be running.

Once you have loaded this, your config should look like:

sudo tljh-config show
https:
  enabled: true
  letsencrypt:
    email: [email protected]
    domains:
    - yourhub.yourdomain.edu

Finally, you can 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.

These certificates are valid for 3 months. The proxy will automatically renew them for you before they expire.

Manual HTTPS with existing key and certificate

You may already have an SSL key and certificate. If so, you can tell your deployment to use these files:

sudo tljh-config set https.enabled true
sudo tljh-config set https.tls.key /etc/mycerts/mydomain.key
sudo tljh-config set https.tls.cert /etc/mycerts/mydomain.cert

Once you have loaded this, your config should look like:

sudo tljh-config show
https:
  enabled: true
  tls:
    key: /etc/mycerts/mydomain.key
    cert: /etc/mycerts/mydomain.cert

Finally, you can reload the proxy to load the new configuration:

sudo tljh-config reload proxy

and now access your Hub securely at https://yourhub.yourdomain.edu.

Troubleshooting

If you’re having trouble with HTTPS, looking at the traefik proxy logs might help.