Skip to content

Latest commit

 

History

History
 
 

jupyterhub

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

JupyterHub Setup Instructions

The Cloud Sandbox setup will automatically install the JupyterHub dependencies. However, additional configuration is required in order to enable user authentication. JupyterHub is installed in the base conda environment by default.

  • Conda install: /opt/conda
  • JupyterHub config: /etc/jupyterhub/jupyterhub_config.py
  • JupyterHub run script: /etc/jupyterhub/runJupyterhub.sh
  • Nginx config: /etc/nginx/conf.d/jupyterhub.conf

Helpful References

Google Authentication

See these instructions for configuring your Google credentials with OAuthenticator. You will create a key on the Google platform and modify the JupyterHub config to have the public key.

Once you've created the key, modify /etc/jupyterhub/jupyterhub_config.py values:

c.GoogleOAuthenticator.client_id = "your_client_id"
c.GoogleOAuthenticator.client_secret = "your_client_secret"

Adding Users

First, create the Linux user account if it doesn't already exist on the system, and add it to the jupyterhub group.

sudo useradd example_user
sudo usermod -aG jupyterhub example_user

Next, fill out the username mapping to map the Google user to a local Unix user. For example:

c.Authenticator.username_map = { "example_user@gmail.com": "example_user" }

Optionally, you can assign administrators using the c.Authenticator.admin_users setting:

c.Authenticator.admin_users = {'example_user@gmail.com'}

Setting up Conda environment

Once the user account is created, that user will need to log in to the machine to set up their Conda environment.

First, if you haven't already, set a password for the user account to login with:

sudo passwd example_user

Then login as that user, initialize Conda, and create a new environment.

su example_user
conda init
conda create -n environment_name ipykernel

The package nb_conda_kernels is already installed and will make the environment visible as long as ipykernel is installed.

The new kernel should now be listed in JupyterHub.

Setting up SSL/HTTPS

It is recommended to run Nginx as a reverse proxy to your JupyterHub instance. Nginx is installed as part of the Cloud Sandbox installation but additional configuration is likely needed for custom deployments. Follow these instructions to configure Nginx.

If you are planning on running SSL/HTTPS, you will need to generate your own certificates and point the Nginx configuration to those.

The Nginx configuration is located in /etc/nginx/conf.d/

Debugging

The JupyterHub logs are part of the jupyterhub.service. To inspect the logs:

sudo systemctl status jupyterhub.service

The JupyterHub service usually needs to be restarted for configuration changes to take effect. To restart the service:

sudo systemctl restart jupyterhub.service