Contents

Setting up Ansible on your local machine

  1. Install conda, either by installing Miniconda (recommended) or Anaconda.

  2. Install Ansible on your local computer by typing in the following into a terminal:

    conda install -c conda-forge ansible

Add the variables specific to your course

  1. Clone or download the rudaux repository.

  2. Open ansible/inventory in a text editor and replace the <STUDENT_HUB_DOMAIN> with your Let’s Encrypt compatible domain name for the student Jupyterhub. Also replace <STUDENT_HUB_IP_ADDRESS> with the IP address for your EC2 instance that will become the student JupyterHub (Reminder this is the value for the IPv4 Public IP address found under the “Description” tab for your EC2 instance on the AWS EC2 Dashboard).

  3. Open ansible/group_vars/hubs/secrets.yml in a text editor and replace each of the <output of: openssl rand -hex 32> with the outputs generated by typing this in the terminal:

    openssl rand -hex 32

    Note: you need to call openssl rand -hex 32 twice in the terminal so that the values for jupyterhub_lti_client_key and jupyterhub_lti_client_secret are different.

  4. Open ansible/group_vars/hubs/jupyterhub.yml and edit the values for each item listed below:

    • jupyterhub_course_name: ‘dsci100’

    • jupyterhub_docker_image: ‘ubcdsci/r-dsci-100’

    • jupyterhub_docker_container: ‘ubcdsci/r-dsci-100:latest’

Note: we have included an example Dockerfiles that could be used for building a Docker image for this course in the rudaux repository in the dockerfiles/dsci-student directory. The base image for this is the r-notebook from the jupyter/docker-stacks repository. Many of the Dockerfiles in that repository would also be good images (or base images) for a student JupyterHub.

Note: we have included a GitHub Actions workflow in this rudaux, .github/workflows/publish_docker_images.yml which is useful for automating the building and versioning of Docker images. Specifically, this workflow is triggered when the Dockerfiles are edited on GitHub, uses Semantics versioning from the commit message to figure out how to bump the version (default is minor if you don’t add specific words to your commit to change this), creates a git tag, and GitHub release based off of the version bump. Then it builds the image and publishes it on DockerHub with the same tag as is in the Git tag and GitHub release.

  1. Add any public IP addresses of folks you need to access the JupyterHubs via ssh (for IT purposes) in ansible/group_vars/all/ssh-public-keys.yml. The key in there is a fake key that is a placeholder.

Build the JupyterHubs using Ansible

  1. To initialize the EC2 instance that will become the student JupyterHub (e.g., update all yum packages and reboot the machine) navigate to the ansible directory and run:

    make playbook PLAYBOOK=init ENV=prod

  2. To install and configure the student JupyterHub run the following from the ansible directory:

    make playbook PLAYBOOK=hub ENV=prod
Set up Amazon Elastic Filesystem (EFS) Add JupyterHub as an App on Canvas