JupyterHub

Guide to setting up a JupyterHub instance for Project Night using The Littlest JupyterHub workflow.

Table of Contents

• Provisioning VM via Terraform
• Configuring Server with Ansible
• Configuring JupyterHub
  • Setting up Development Enviroment for All Users
  • User Workflow
• Delete JupyterHub Resources

Provisioning VM via Terraform

You will need to have access to the Chicago Python organization on Terraform Cloud.

1. terraform login
2. Create DigitalOcean Access Token using Web Interface; save token
3. Add SSH key to DigitalOcean; update name in main.tf

terraform login
export DIGITALOCEAN_ACCESS_TOKEN=[token from above]

# go to the terraform folder in this repo
cd terraform

# initialize terraform providers
terraform init

# view terraform plan
terraform plan

# apply plan if it looks good
terraform apply

Configuring Server with Ansible

1. Requires ansible installed on the command line

# go to ansible folder in this repo
cd ansible

# run playbook
ansible-playbook -i hosts install_and_configure_jupyterhub.yaml --extra-vars "admin_user_id=[admin-user-id] admin_email=[your-email-for-lets-encrypt] domain=jupyterhub.sivji.dev"

Note: might need to delete the jupyterhub.[yourdomain] entry from ~/.ssh/known_hosts

Configuring JupyterHub

JupyterHub is available on the domain configured it with. You can use your [admin-user-id] to login. The password you login with will be your password for this installation.

Setting up Development Enviroment for All Users

JupyterHub docs

1. Login with your admin user account
2. pip install the required files

Recommend using a requirements.txt file to ensure you get the correct versions as required.

The docs have a guide on updating Python versions, but I have not been able to get it to work. My solution is to fork the-littlest-jupyterhub repo and change the miniconda version in the ensure_user_environment function. Also removed the sha check. Then I pointed the ansible playbook to the bootstrap.py in my fork.

User Workflow

1. Users can go to your domain and create an account to use JupyterHub
2. We can use nbgitpuller to create a link that users can use to fork a git repo to their JupyterHub workspace.

Delete JupyterHub Resources

export DIGITALOCEAN_ACCESS_TOKEN=[token from above]

# go to the terraform folder in this repo
cd terraform
terraform destroy