How to Add Folks to the 2i2c Hub

We use GitHub Teams to manage access to the 2i2c Hub. There are three different patterns of access:

1. Individually-managed long-term access for NASA-Openscapes mentors and others
2. Access for participants in a NASA-Openscapes champions cohort
3. Access for participants in a workshop

Access for for cohorts and workshop participants currently uses the same workflow.

We are also working on a method to give just-in-time access for specific workshops without using GitHub Teams or other managed access. Details of this process will be added as we finalize it.

Individual long-term access

Individuals are given long-term access by adding them as members of the LongtermAccess-2i2c team in the NASA-Openscapes organization.

This is the workflow to add individual users one by one.

1. Share Google Form with users needing long-term access

Ask users: Please add your GitHub Username to this Google form for NASA Openscapes JupyterHub Access. Requests also sometimes come in via email directly from NASA mentors.

2. Google Form response setup

Set the form responses in Openscapes_JupyterHubAccess to notify when there are responses: Click on Responses > click three vertical dots and then check “email notification.”

3. Email alert of new signup

When you get an email click ‘view response’ (not view summary)

4. Copy GitHub username

On the response page, copy the Github Username

5. Add GitHub username to the GitHub Team

Tip

If you are adding many new mentors to the long-term access team, you can use the same steps as for adding workshop participants

Go to the NASA Openscapes LongtermAccess-2i2c Team in GitHub > Click Add member > Paste GitHub username. Note there are separate GitHub Teams for Champions Cohorts and workshops.

GitHub may ask you for 2-factor authentication for the first one you add in a batch, not after that.

People may see invitation notifications in two ways; in GitHub itself, and/or via email. They must accept the invitation to be able to access the Hub. This is what it looks like in their email inbox:

This is what the invitation looks like in the GitHub website interface - clicking the yellow banner notification leads to the invitation:

6. Email confirmation

Go back to the Google form response and grab their email address. Send the following emails to the person.

Email for General requests: 

Subject: NASA Openscapes Access to 2i2c Hub

Hi [FIRST NAME],

I have added you to the NASA Openscapes 2i2c Jupyter Hub. Here is the link to the hub: https://openscapes.2i2c.cloud/

There is a getting started guide in the NASA Earthdata Cloud Cookbook here: https://nasa-openscapes.github.io/earthdata-cloud-cookbook/. You can see policies for hub use here: https://nasa-openscapes.github.io/earthdata-cloud-cookbook/policies-admin/, and policies and best practices for data storage here https://nasa-openscapes.github.io/earthdata-cloud-cookbook/policies-admin/data-policies.qmd

We’d love to know about the kind of work you are doing on the hub. Please add a brief description of your progress as you go at https://github.com/NASA-Openscapes/2i2cAccessPolicies/discussions/2. We will follow up in the next few months. 

Best,

7. Register date in Form Response Sheet

In the Form Response Sheet, in column Added to NASA 2i2c hub add the date they were added to the Hub, or if the request came via email add a new row - in part so that we as admins knew if someone had already fulfilled the request. Check Column A for the date of the form request.

Directions for invitees

1. Please go to https://github.com/nasa-openscapes

2. Click the big yellow bar that says “you’ve been invited” 

3. Not seeing that bar? 

   1. Are you logged into GitHub.com?

   2. Have you shared your GitHub username via this form?

   3. You can also check your email that you use for GitHub and look for an invitation from GitHub and NASA-Openscapes

Adding Champions cohorts as a batch

Participants in the Champions program workshops are given Openscapes 2i2c JupyterHub access, as are participants in certain workshops run by NASA Openscapes Mentors.

Note

We have a newly developed process for giving people short-term access to the hub for workshops, with low overhead for instructors and particpants. This process removes the need to add people to a GitHub team, and gives participants “just in time” access to a special workshop hub with a username and shared workshop-specific password. Policies and instructions for this currently being developed.

We use a dedicated GitHub Organization - nasa-openscapes-workshops - to manage access, with GitHub Teams for Champions Cohorts and certain workshops.

1. Create a team in nasa-openscapes-workshops

There are several teams in this organization; the AdminTeam team is for members who have permission to create teams and add members to teams.

• If this is for a new champions cohort, name the team nasa-champions-yyyy
• If this is for a one-off workshop, name the team [workshop-name]-[workshop-date], with workshop date in the format yyyy-mm-dd

2. Add team name to workshop registry

We keep a registry of all workshops in this sheet. Add the name of the GitHub team to 2i2c access type column in the appropriate row.

3. Add teams to 2i2c Hub configuration

Make a pull request to the Openscapes common.values.yaml file in the 2i2c infrastructure repository, adding the new team to the allowed-teams item in whichever sections are appropriate for your workshop/cohort (likely all of them):

• display_name: Python
• display_name: R
• display_name: Matlab
• display_name: "Bring your own image"

These will determine which images are available to participants when they log in to the Hub.

Team specification is in the form [github-org]:[team] (e.g., nasa-openscapes-workshops:champions-access-2i2c-2024)

You also need to add the team to the allowed_organizations item under hub > config > GitHubOAuthenticator

You can see an example pull request here.

4. Share Google Form with participants needing access for the cohort or workshop

Ask users: Please add your GitHub Username to this Google form for NASA Openscapes JupyterHub Access.

5. Add users to a Team in a batch using kyber

Tip

Do this fairly close to the day of the workshop to try to get the greatest number particpants to have filled out the form, and reduce the number of manual additions on the day of the workshop.

1. Open the spreadsheet of form responses, select the GitHub usernames from the rows containing the people you want to add, and copy it to your clipboard.

Tip

Some workshop instructors will use their own form to record participants, rather than the Openscapes form. In that case use those responses instead. But do paste all those rows into this Main form; it is important that we have a record of everyone using the Hub and a way to contact them via email.

2. In R, do the following:

library(kyber)
library(datapasta)

# Run datapasta::tribble_paste() or use the RStudio Addin 'Paste as tribble'

# assign the pasted output to a new object:
responses <- tribble::tribble(
    # The stuff that was pasted
)

The responses object will have a column of usernames. It likely won’t be called username, so you can rename it or even easier, change the name inside the tribble::tribble() call that you pasted. Verify these are the usernames you want to add, and run kyber::add_team_members() as follows:

team_name <- "the name of the github team you want to add to"

add_team_members(
  team_name, 
  members = responses$username, 
  org = "nasa-openscapes-workshops"
)

3. Go the appropriate team in the nasa-openscapes-workshops organization and verify that there are the appropriate “pending members”:

4. Go back to the spreadsheet of responses, and fill in the Added to NASA 2i2c hub column with the date you added them.

Directions for workshop participants

1. Please go to https://github.com/nasa-openscapes-workshops

2. Click the big yellow bar that says “you’ve been invited” 

3. Not seeing that bar? 

   1. Are you logged into GitHub.com?

   2. Have you shared your GitHub username via this form?

   3. You can also check your email that you use for GitHub and look for an invitation from GitHub and NASA-Openscapes-Workshops

Troubleshooting

Users get 403 error

This is a common issue. User must find email notification from GitHub and accept invitation. If they had clicked in email to accept but did not complete accepting in GitHub, edit their invitation in GitHub to uninvite and reinvite. They should get a new email to accept.

Didn’t get email

Go to https://github.com/nasa-openscapes-workshops, see the big yellow bar that says You’re invited. 

Notes on process and any issues

Yuvi has started documenting the issues we are running into here -> https://hackmd.io/tWfqVai4SDC1CbQ4mhfIbw