02_Instructor_Setup.Rmd

# (PART\*) Instructor Setup {-}

```{r, include = FALSE}
ottrpal::set_knitr_image_path()
knitr::opts_chunk$set(out.width = "100%")
```

# Overview 

<br>

The setup instructions are presented in two parts:

- **Instructor Setup** (this section): covers everything needed to set up yourself and any co-instructors or TAs to work on AnVIL.  Depending on your team and funding, *you may only need to do these steps once* (and then make updates on an as-needed basis for changes in team members or funding).
- [**Running the Class**](#run-class): covers how to grant your students access to AnVIL.  These steps will need to be *repeated for each new offering of the course*.

## What do I need to do?

You may not need to do everything in the instructor setup section!

This section contains instructions for setting up billing from scratch.  If your funding is being managed by a third party (e.g. through a funding mechanism such as [STRIDES](https://datascience.nih.gov/strides) or through your institution) you can skip some steps.  The table below provides guidance on which steps you will need to complete:

| Task | Self-managed Funding | 3rd-party Funding |
|:----|:---:|:----:| 
|[Create Google Account](#instructor-google-account)|Yes|Yes|
|[Set up Google Billing](#google-billing-account)|Yes|Probably No (ask your funding manager)|
|[Create Instructor/TA Group](#instructor-group)| Only if you have co-instructors or TAs|Only if you have co-instructors or TAs|
|[Set up Terra Billing Projects](#terra-billing-projects)|Yes|Probably Yes (ask your funding manager)|

# Create Google account {#instructor-google-account}

AnVIL uses [Terra](https://anvil.terra.bio/) to run analyses. Terra operates on Google Cloud Platform, so you’ll pay for all storage and analysis costs through a Google account linked to Terra. The costs are the standard Google Cloud Platform fees for storing and moving data as well as executing an analysis. These costs are passed along through Terra without any markup.

## Create a Google Account {#google-account}

Terra operates on Google Cloud Platform, so you will need a (free) Google account which will allow you to access the Terra platform to manage students and in-class analyses.

Your Google account will also (1) allow you to manage billing yourself or (2) allow a Program Manager to do so on your behalf.

```{r, child=c("_child_create_google_account.Rmd")}

```

## Sign in to Terra

You need to sign into Terra to allow Billing Project managers to add you to projects and/or Workspaces. [Launch Terra](https://anvil.terra.bio/#workspaces), and you should be prompted to sign in with your Google account.

You can always access Terra by going to [`anvil.terra.bio`](https://anvil.terra.bio/), or by clicking the link on the AnVIL home page.

```{r, echo=FALSE, fig.alt='Screenshot of the AnVIL home page. The button to "launch Terra" is highlighted.'}
ottrpal::include_slide("https://docs.google.com/presentation/d/1-PVlDAzmDncjcCHIy9ZyR3ROyPpfjrg46LhEQopDc1Q/edit#slide=id.g22c9add987a_0_5")
```

# Set up Google Billing {#google-billing-account}

Google Billing Accounts are how you pay Google for you and your students' cloud costs.  Depending on how you are being funded, this may be taken care of for you. If your funding is being managed by a third party (e.g. through a funding mechanism such as [STRIDES](https://datascience.nih.gov/strides), or through your institution), contact them to determine whether you need to do any billing administration through Google.  If not, you can proceed directly to [create Instructor Group](#instructor-group).

::: {.warning}
```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_instructor_STRIDES.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```
:::

If you are using a third party funding mechanism but you would like to get started exploring AnVIL right away, you can optionally follow the instructions below to activate Google's free credits.  These should be sufficient for you to experiment with a few exercises yourself and learn how AnVIL works, while you work on getting funding set up for your class.

## Before You Start

- If you are managing your own billing, you will need a **credit card or bank account** to get started.  Google provides a free trial for first-time users, but payment information is still needed for verification purposes. Don't worry!  If using the free trial, **you won't be billed until you explicitly turn on automatic billing**.
- Before setting up billing yourself, you may want to check with your institutional procurement office and see if they have a preferred account set-up method with Google (such as a third party reseller or an existing account).

## Google Billing Account

AnVIL operates on Google Cloud Platform, and does not charge any markup.  Rather than paying Terra or AnVIL, users set up billing directly with Google Cloud Platform.

**Make sure to use the same Google account ID you use to log into Terra for Google Cloud Billing.**

To set up billing, you must first create a **Google “Billing Account”**.

:::{.notice}
**Tip**:  You can create multiple Billing Accounts associated with your Google ID.

- A single Billing Account can fund multiple courses, sections, or iterations of a course, as long as they have a common funding source.
- But, if courses are funded separately, we recommend creating separate Billing Accounts
:::

### Create a Google Billing Account

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_google_billing_create_account.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

### Add Users or Viewers (optional)

If you have a finance administrator who needs access to a Billing Account, you can add them with a few different levels of permissions.  Generally the most useful are:

- **Users** have a great deal of power over spending - they can create new "Billing Projects" and control who can spend money on those projects.  If you have an accounts manager responsible for expenses, it may make sense to add them as a Billing Account User.  If you wish to retain full control over who can spend money, you should not add any Users.
- **Viewers** can see the activity in the Billing Account but can’t make any changes.  This can be useful for finance staff who need access to the reports, or for anyone who needs to monitor spending.

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_google_billing_add_member.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

## Add Terra to Google Billing Account

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_google_billing_add_terra.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

# Create Instructor Group {#instructor-group}

Groups enable you to share AnVIL resources and manage permissions for many people at once.  If you have co-instructors or TAs who will be teaching with you, we recommend setting up an "instructor" Group where you can share materials under development and any other resources that are not meant to be shared with students.  If you are teaching by yourself, you can proceed directly to [Terra Billing Projects](#terra-billing-projects).

:::{.notice}
Depending on your needs, you may want to

- Create a single Group that persists across course offerings.  This is convenient if the same people will be teaching the course multiple times; you will not have to re-share resources each time.
- Create a new Group for each offering of the course.  This can be useful if you have different TAs for every offering and you don't want them to access materials and funding for past and future offerings.

You can always add/remove Groups and Group members later, so we recommend starting out with a single instructor group.  You can decide later if you want to create a new Group for the next course.
:::

Choose an informative, unique Group name. We suggest a combination of institution-class-role (e.g., `jhu-bio101-instructors`). Only letters, numbers, underscores, and dashes are allowed in Group names.

## Create Terra Group

To create a Group:

::::{.borrowed_chunk}
```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_terra_group_create.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```
::::

You now have a unique **instructor Group**.

## Add Instructors and TAs to Group

Now that your instructor Group has been created, you should add any additional instructors and TAs. You should also ensure that they have the correct permissions.

:::{.notice}
Users can be added to a Group as either **Admins** or **Members**.  Admins can add and remove members from the group.

Group roles only affect whether or not someone can add and remove members from the Group.  They do not grant special privileges with respect to Terra resources (Billing Projects and Workspaces).

However, an Admin for the Group can *indirectly* grant access to Terra resources.  By adding someone to the Group, they grant that person access to any Terra resources that the Group has been given permission to access.
:::

Often it's appropriate to add any **co-instructors as Admins, with TAs as Members**.

To add someone to your group:

:::: {.borrowed_chunk}
```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_terra_group_add_member.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```
::::


# Set up Terra Billing Projects {#terra-billing-projects}

Terra Billing Projects are how you grant people (including yourself!) permission to compute on AnVIL.  By adding someone to your Billing Project, you enable them to use your funding to carry out activities on AnVIL.

Depending on how you are being funded, this may be taken care of for you. If your funding is being managed by a third party (e.g. through a funding mechanism such as [STRIDES](https://datascience.nih.gov/strides), or through your institution), contact them to determine whether you should create Terra Billing Projects yourself.

The first set of instructions below walk you through creating a Terra Billing Project.  **If someone else has provided a billing project**, you can skip down to [adding instructors to Billing Project](#add-instructors-billing-project).


## Create Terra Billing Projects

::: {.warning}
To create a Billing Project, you need access to a Google Billing Account.

- If you set up Google Billing yourself, you're good to go!  Just make sure to use the same Google Account when logging in to Terra.
- If a third party is handling Google Billing, you likely do not need to log in to Google Billing yourself; you should be able to follow the instructions below to create a Billing Project within Terra.  If you run into trouble, check with your funding manager to confirm:
    - They have set up a Google Billing Account
    - They have added you to the Account as a "User" (or higher)
    - You are using the correct Google ID (i.e. email address) to log in to Terra
    - They have not already created a Billing Project for you
:::

It's often beneficial to set up two separate Billing Projects for a course:

1. **Instructor/TA** - used to fund development and testing of the material.  It can persist for multiple sessions of the course.
2. **Student** - funds all student activity, and is deactivated at the end of the course activities.

Having separate Billing Projects is not required, but can make management easier, particularly when it comes to shutting things down.

**Note:** Terra Billing Projects need unique names.  One option is to use a combination of institution-class-term (e.g. `jhu-bio101-2022SP`).

To create a Terra Billing Project:

:::: {.borrowed_chunk}
```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_terra_billing_project_create.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```
::::

## Add Instructors to Billing Project {#add-instructors-billing-project}

Adding someone to a Billing Project enables them to compute on AnVIL, funded by the Billing Project.

::: {.warning}
To add members to a Billing Project, you must be an "Owner" of the Billing Project.

- If you created the Billing Project yourself, you're good to go!
- If a third party created the Billing Project, check to see whether you are an Owner or a User.  If you are not an Owner, you will need to contact your funding manager.  They can either make you an Owner, or can add other team members to the Billing Project themselves.
:::

You can add individual users to a Billing Project, or you can add a Terra Group, which will enable everyone in the Group to charge to the Billing Project.

- To add an individual user, you will need to know the email address they will be using to access AnVIL.
- To add a Group, you will need the email address associated with the Group.

### Find Group email {#group-email}

If you want to add a Terra Group (such as your "instructor" Group) to your Billing Project, you can find the Group email address on the Group Managment page:

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_terra_group_find_email.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

Now that you have the Group email address, you can add the group to your Billing Project.

### Add members to Billing Project

:::{.notice}
Users can be added to a Billing Project as either **Owners** or **Users**.  Owners can add and remove users from the Billing Project (including other Owners!).  This means Billing Project Owners have a great deal of power over how money can be spent.

It’s often a good idea to have at least one other Owner of a Billing Project in order to avoid getting locked out, in case the original Owner leaves or loses access to their account.  But you should exercise caution when selecing Billing Project Owners.

When teaching with a team, it may make sense to add only those most comfortable with Terra and/or most involved in Terra administration as Owners, and to add everyone else as Users.  This can be done by adding the Owners individually as Owners, and then adding the Instructor Group as User.
:::

:::: {.borrowed_chunk}
```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_terra_billing_project_add_member.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```
::::

# Wrap-up

**Congratulations! You have successfully set up AnVIL for your teaching team!**

You and your team members should be free to develop and test content, funded by your Billing Project.  Check out the *Content Preparation* section for more information about how to use or develop content on AnVIL.

When you're ready to set things up for your students

- [**Running the Class**](#run-class) has instructions on getting everything set up to teach your course or workshop
- [**Student Instructions**](#student-instructions) has student-facing instructions that you can share with your students so they can sign up for an AnVIL account and access any necessary resources